# RecurringInvoiceScheduleCreateDto

A model the API reference uses in a request or a response. The operation pages link every field typed as this model here.

Input DTO for creating a recurring invoice schedule.

## Fields
- `name` (string) required: Operator-facing name for the series. (nullable, max length 200)
- `description` (string): Optional operator-facing description. Conditional: When Description is not null. Max length: 1000. (nullable)
- `schedule` ([ContractSchedule](https://devportal.demo.winkpg.io/docs/api/models/ContractSchedule.md)) required: The recurrence rule (frequency, interval, start date, optional end date).
  Fields:
  - `frequency` ([Frequency](https://devportal.demo.winkpg.io/docs/api/models/Frequency.md)): The type of the recurrence rule.
    Values:
    - `Secondly`
    - `Minutely`
    - `Hourly`
    - `Daily`
    - `Weekly`
    - `Monthly`
    - `Yearly`
  - `count` (integer(int32)): The number of occurrences in a particular recurrence. (nullable)
  - `until` (string(date-time)): The datetime that bounds the current recurrence. (nullable)
  - `interval` (integer(int32)): The recurrence interval.
  - `bySecond` (array<integer(int32)>): BySecond rule modifier. (nullable)
  - `byMinute` (array<integer(int32)>): BySecond rule modifier. (nullable)
  - `byHour` (array<integer(int32)>): BySecond rule modifier. (nullable)
  - `byDay` (array<[ContractScheduleByDayRule](https://devportal.demo.winkpg.io/docs/api/models/ContractScheduleByDayRule.md)>): Week day rule modifier. (nullable)
  - `byMonth` (array<integer(int32)>): Month day rule modifier. (nullable)
  - `byMonthDay` (array<integer(int32)>): Month days rule modifier. (nullable)
  - `byYearDay` (array<integer(int32)>): Year days rule modifier. (nullable)
  - `byWeekNumber` (array<integer(int32)>): Week number rule modifier. (nullable)
  - `bySetPosition` (array<integer(int32)>): BySetPosition rule modifier. (nullable)
  - `firstDayOfWeek` ([DayOfWeek](https://devportal.demo.winkpg.io/docs/api/models/DayOfWeek.md)): The first day of week, used in calculating weekday-based recurrences (nullable)
    Values:
    - `Sunday`
    - `Monday`
    - `Tuesday`
    - `Wednesday`
    - `Thursday`
    - `Friday`
    - `Saturday`
  - `nextScheduledRun` (string(date-time)): The next computed billing date, updated after each billing run. Null for contracts that  have never been scheduled or have ended. (nullable)
  - `startDate` (string(date-time)): The earliest date on which this contract is eligible to bill. Set by the user  when creating the contract (defaults to the creation date) and may be set to a  future date to delay first billing. The recurrence engine anchors expansion to  this date and the daily billing job will not fire a contract whose  `startDate` is in the future.                Null on contracts created before this field existed. When it is null, the server  anchors the schedule on the contract's creation time, or on the current time when  that is also absent; callers that compute a schedule themselves should apply the  same fallback. (nullable)
- `endAfterOccurrences` (integer(int32)): Optional cap on the total number of invoices the series will generate. Conditional: When EndAfterOccurrences is not null. Must be > 0. (nullable)
- `autoSend` (boolean): When true, each generated invoice is auto-sent via the standard send workflow.
- `paymentLinkExpiryHours` (integer(int32)): Optional payment-link expiry (hours) applied when auto-sending. (nullable)
- `viewTokenExpiryDays` (integer(int32)): Optional view-token expiry (days) applied when auto-sending. (nullable)
- `customMessage` (string): Optional custom recipient message applied when auto-sending. Conditional: When CustomMessage is not null. Max length: 2000. (nullable)
- `recipientId` (string(uuid)) required: Who the generated invoices are billed to.
- `recipientType` ([InvoicePartyType](https://devportal.demo.winkpg.io/docs/api/models/InvoicePartyType.md)): The type of recipient entity.
  Values:
  - `GatewayOwner`: Platform-level gateway owner.
  - `Reseller`: Reseller entity.
  - `Merchant`: Merchant entity.
  - `Customer`: End customer.
- `currency` (string) required: ISO 4217 currency code for generated invoices. (nullable, min length 3, max length 3, pattern ^[A-Za-z]{3}$)
- `paymentTermsValue` ([PaymentTerms](https://devportal.demo.winkpg.io/docs/api/models/PaymentTerms.md)): Payment terms applied to generated invoices. (nullable)
  Values:
  - `DueOnReceipt`: Payment due immediately upon receipt.
  - `Net15`: Payment due within 15 days of issue.
  - `Net30`: Payment due within 30 days of issue.
  - `Net45`: Payment due within 45 days of issue.
  - `Net60`: Payment due within 60 days of issue.
  - `Net90`: Payment due within 90 days of issue.
  - `Custom`: Custom number of days specified via InvoiceConsts.
- `customPaymentDays` (integer(int32)): Custom number of days when PaymentTerms is Custom. (nullable)
- `allowPartialPayment` (boolean): Whether partial payments are allowed on generated invoices. (nullable)
- `minimumPaymentAmount` (number(double)): Minimum payment amount when partial payments are enabled. (nullable)
- `partialPaymentTolerance` (number(double)): Auto-mark-paid tolerance for generated invoices. (nullable)
- `allowedPaymentMethods` (array<string>): Subset of supported payment methods allowed on generated invoices. (nullable)
- `vaultRestriction` ([VaultRestriction](https://devportal.demo.winkpg.io/docs/api/models/VaultRestriction.md)): Vault restriction applied to generated invoices. (nullable)
  Values:
  - `Any`: Allow any payment method (new or saved).
  - `AllowNewAndSaved`: Allow both new and saved payment methods.
  - `SavedOnly`: Only allow previously saved (vaulted) payment methods.
- `hppPageId` (string(uuid)): Linked HPP configuration id. (nullable)
- `templateId` (string(uuid)): Invoice style/template reference (styling only). (nullable)
- `invoiceLevelDiscount` ([InvoiceDiscountDto](https://devportal.demo.winkpg.io/docs/api/models/InvoiceDiscountDto.md)): Optional invoice-level discount applied to generated invoices.
  Fields:
  - `type` ([DiscountType](https://devportal.demo.winkpg.io/docs/api/models/DiscountType.md)): The type of discount applied to a line item or invoice.
    Values:
    - `Percent`: Percentage discount (e.g., 10%).
    - `Flat`: Flat dollar amount discount (e.g., $5.00).
  - `value` (number(double))
  - `description` (string): (nullable)
- `reminderConfig` ([InvoiceReminderConfigDto](https://devportal.demo.winkpg.io/docs/api/models/InvoiceReminderConfigDto.md)): Reminder configuration applied to generated invoices.
  Fields:
  - `preDueDays` (array<integer(int32)>): Days before the due date to send a reminder (for example 7, 3, 1). Null or omitted inherits the  tenant default; an empty list sends no pre-due reminders for this invoice. (nullable)
  - `dueDayReminder` (boolean): (nullable)
  - `postDueDays` (array<integer(int32)>): Days after the due date to send a reminder (for example 1, 7, 14, 30). Null or omitted inherits  the tenant default; an empty list sends no scheduled post-due reminders for this invoice. (nullable)
  - `postDueRecurringDays` (integer(int32)): (nullable)
  - `stopOnPaid` (boolean): (nullable)
  - `maxReminders` (integer(int32)): (nullable)
  - `dunningEndAction` ([DunningEndAction](https://devportal.demo.winkpg.io/docs/api/models/DunningEndAction.md)): (nullable)
    Values:
    - `None`: No automatic action taken.
    - `MarkUncollectible`: Transition the invoice to Uncollectible.
    - `Close`: Transition the invoice to Closed.
  - `daysUntilUncollectible` (integer(int32)): (nullable)
- `billerSnapshot` ([InvoicePartySnapshotDto](https://devportal.demo.winkpg.io/docs/api/models/InvoicePartySnapshotDto.md)): Biller snapshot frozen onto each generated invoice at issue time.
  Fields:
  - `name` (string): (nullable, max length 200)
  - `email` (string): (nullable, max length 256)
  - `phone` (string): (nullable, max length 30)
  - `addressLine1` (string): (nullable, max length 200)
  - `addressLine2` (string): (nullable, max length 200)
  - `city` (string): (nullable, max length 100)
  - `state` (string): (nullable, max length 100)
  - `postalCode` (string): (nullable, max length 20)
  - `country` (string): (nullable, max length 100)
  - `companyName` (string): (nullable, max length 200)
  - `taxId` (string): (nullable, max length 50)
  - `logoUrl` (string): (nullable, max length 2048)
- `recipientSnapshot` ([InvoicePartySnapshotDto](https://devportal.demo.winkpg.io/docs/api/models/InvoicePartySnapshotDto.md)): Recipient snapshot frozen onto each generated invoice at issue time.
  Fields:
  - `name` (string): (nullable, max length 200)
  - `email` (string): (nullable, max length 256)
  - `phone` (string): (nullable, max length 30)
  - `addressLine1` (string): (nullable, max length 200)
  - `addressLine2` (string): (nullable, max length 200)
  - `city` (string): (nullable, max length 100)
  - `state` (string): (nullable, max length 100)
  - `postalCode` (string): (nullable, max length 20)
  - `country` (string): (nullable, max length 100)
  - `companyName` (string): (nullable, max length 200)
  - `taxId` (string): (nullable, max length 50)
  - `logoUrl` (string): (nullable, max length 2048)
- `lineItems` (array<[InvoiceLineItemInputDto](https://devportal.demo.winkpg.io/docs/api/models/InvoiceLineItemInputDto.md)>) required: Line items copied onto each generated invoice. (nullable)
  Fields of each item:
  - `parentLineItemId` (string(uuid)): Parent line item ID for bundle/discount/tax line hierarchies. (nullable)
  - `name` (string): Product name snapshot (formal product name). (nullable, max length 200)
  - `description` (string) required: Line item description shown on PDF and HPP. (nullable, max length 500)
  - `notes` (string): Per-line notes visible to the biller only. (nullable, max length 500)
  - `productId` (string(uuid)): Optional link to the product catalog. (nullable)
  - `productCode` (string): SKU or product code. (nullable, max length 50)
  - `unitOfMeasure` (string): Unit of measure (e.g., "each", "hour", "GB"). (nullable, max length 50)
  - `commodityCode` (string): Commodity code sent as enhanced (Level 3) card data when the invoice is paid by card. At most  25 characters. (nullable, max length 25)
  - `quantity` (number(double)): Quantity (default 1). (greater than 0)
  - `unitPrice` (number(double)): Unit price. (min 0)
  - `cost` (number(double)): Cost for margin tracking. (nullable)
  - `pricingSource` ([PricingSource](https://devportal.demo.winkpg.io/docs/api/models/PricingSource.md)): How the unit price was determined. (nullable)
    Values:
    - `Catalog`: Price taken from the product catalog at time of invoicing.
    - `Override`: Price manually overridden by the user.
    - `Promotion`: Price determined by a promotion or coupon.
    - `Contract`: Price from a negotiated contract or quote.
  - `discountType` ([DiscountType](https://devportal.demo.winkpg.io/docs/api/models/DiscountType.md)): Type of discount applied to this line item. (nullable)
    Values:
    - `Percent`: Percentage discount (e.g., 10%).
    - `Flat`: Flat dollar amount discount (e.g., $5.00).
  - `discountValue` (number(double)): Discount value (percentage or flat amount). (nullable)
  - `taxRateId` (string(uuid)): Reference to a reusable tax rate definition. (nullable)
  - `taxRatePercent` (number(double)): Snapshot of the tax rate percentage. (nullable)
  - `taxJurisdiction` (string): Tax jurisdiction (state/country). (nullable, max length 100)
  - `taxRateSource` ([InvoiceTaxRateSource](https://devportal.demo.winkpg.io/docs/api/models/InvoiceTaxRateSource.md)): Optional. Where `taxRatePercent` came from. Provider is stored only when  `taxRateProviderName` is supplied and `taxRateId` is not; any other  combination is stored as Catalog when a rate id is named, otherwise Manual. Provenance is  recorded as supplied, like the percentage: the platform does not verify that a lookup ran. (nullable)
    Values:
    - `Manual`: The operator typed the percentage, or nothing recorded where it came from.
    - `Catalog`: The percentage was snapshotted from one of the biller's named tax rates.
    - `Provider`: The percentage was sourced from the merchant's bound tax provider.
  - `taxRateProviderName` (string): Optional. The tax provider that sourced the percentage; meaningful only with a Provider source. (nullable, max length 50)
  - `taxCode` (string): Tax code snapshotted from product or overridden. (nullable, max length 50)
  - `isTaxable` (boolean): Whether tax applies to this line. (nullable)
  - `isDiscountLine` (boolean): Indicates this is a discount adjustment line. (nullable)
  - `isSystemGenerated` (boolean): Indicates this line was auto-generated. (nullable)
  - `isOptional` (boolean): For quotes-to-invoices flow: whether this line is optional. (nullable)
  - `revenueAccount` (string): GL account for revenue recognition. (nullable, max length 100)
  - `recognitionStartDate` (string(date-time)): Revenue recognition start date. (nullable)
  - `recognitionEndDate` (string(date-time)): Revenue recognition end date. (nullable)
  - `attributes` (object): Extensibility metadata (key-value pairs). (nullable)
- `customFields` (array<[CustomFieldValueDto](https://devportal.demo.winkpg.io/docs/api/models/CustomFieldValueDto.md)>): Custom field values copied onto each generated invoice. (nullable)
  Fields of each item:
  - `id` (string(uuid))
  - `key` (string) required: (nullable, max length 100)
  - `label` (string): (nullable, max length 200)
  - `value` (string): (nullable, max length 2000)
- `notes` (array<[EntityNote](https://devportal.demo.winkpg.io/docs/api/models/EntityNote.md)>): Internal notes copied onto each generated invoice. (nullable)
  Fields of each item:
  - `id` (string(uuid))
  - `enteredBy` (string(uuid))
  - `timestamp` (string(date-time))
  - `enteredByName` (string): Denormalized display name of the user who created the note.  Populated at creation time from `ICurrentUser` to avoid N+1 lookups when rendering. (nullable)
  - `content` (string): (nullable, min length 0, max length 1000)
- `recipientNote` (string): Recipient-facing note copied onto each generated invoice. (nullable)
- `footerText` (string): Footer / terms text copied onto each generated invoice. (nullable)
- `billerId` (string(uuid)) required: The billing entity id. Cannot be changed after creation.
- `billerType` ([InvoicePartyType](https://devportal.demo.winkpg.io/docs/api/models/InvoicePartyType.md)): The type of billing entity.
  Values:
  - `GatewayOwner`: Platform-level gateway owner.
  - `Reseller`: Reseller entity.
  - `Merchant`: Merchant entity.
  - `Customer`: End customer.

## See also

- [All documentation](https://devportal.demo.winkpg.io/llms.txt): the machine-readable index of every public page on this site.