# InvoiceCreateDto

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 new invoice.

## Fields
- `recipientId` (string(uuid)) required: Recipient entity ID.
- `recipientType` ([InvoicePartyType](https://devportal.demo.winkpg.io/docs/api/models/InvoicePartyType.md)): Recipient entity type.
  Values:
  - `GatewayOwner`: Platform-level gateway owner.
  - `Reseller`: Reseller entity.
  - `Merchant`: Merchant entity.
  - `Customer`: End customer.
- `currency` (string) required: ISO 4217 currency code. (nullable, min length 3, max length 3, pattern ^[A-Za-z]{3}$)
- `paymentTermsValue` ([PaymentTerms](https://devportal.demo.winkpg.io/docs/api/models/PaymentTerms.md)): Standard payment terms. (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. Conditional: When PaymentTermsValue == Custom. Must be > 0. (nullable)
- `dueDate` (string(date-time)): Manual due date override (used if PaymentTerms is null). (nullable)
- `allowPartialPayment` (boolean): Whether partial payments are allowed. (nullable)
- `minimumPaymentAmount` (number(double)): Minimum payment amount when partial payments are enabled. Conditional: When AllowPartialPayment is true and MinimumPaymentAmount is not null. Must be > 0. (nullable)
- `partialPaymentTolerance` (number(double)): Auto-close tolerance. (nullable)
- `depositType` ([InvoiceDepositType](https://devportal.demo.winkpg.io/docs/api/models/InvoiceDepositType.md)): When set, requests an up-front deposit on the invoice: the payer is charged exactly the deposit  first, then the remaining balance. Null means no deposit is requested. When set, `depositValue`  is required. (nullable)
  Values:
  - `Percentage`: Deposit is a percentage (0 < value < 100) of the invoice grand total.
  - `FixedAmount`: Deposit is a fixed currency amount (0 < value < grand total).
- `depositValue` (number(double)): The deposit percentage (e.g. 25 for 25%) when `depositType` is  `Percentage`, or the fixed deposit amount when it is  `FixedAmount`. Must be positive; the resolved amount must be  strictly less than the invoice total. Required: When DepositType is not null. Must be > 0. Must be < 100. (nullable)
- `depositDueDate` (string(date-time)): Optional deposit due date, distinct from the balance `dueDate`. When set, it must not  be after the balance due date. Conditional: When DepositType is not null. (nullable)
- `allowedPaymentMethods` (array<string>): Subset of biller's supported payment methods for this invoice. Conditional: When AllowedPaymentMethods is not null. (nullable)
- `vaultRestriction` ([VaultRestriction](https://devportal.demo.winkpg.io/docs/api/models/VaultRestriction.md)): Controls whether new or saved payment methods are allowed. (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.
- `applyConvenienceFee` (boolean): Per-invoice override of the merchant's convenience fee on this invoice's payments:  `true` applies it, `false` suppresses it, and `null` (the default, and the  behaviour of any payload that omits the field) inherits the merchant and feature decision.  An override can suppress a fee but can never create one: `true` applies the fee only  when invoice convenience fees are enabled for the tenant and the merchant has a  convenience-fee configuration, and the platform's compliance rules still govern whether the  resulting transaction keeps the fee. (nullable)
- `hppPageId` (string(uuid)): Linked HPP configuration ID. (nullable)
- `templateId` (string(uuid)): Invoice style/template reference. (nullable)
- `invoiceLevelDiscount` ([InvoiceDiscountDto](https://devportal.demo.winkpg.io/docs/api/models/InvoiceDiscountDto.md)): Invoice-level discount.
  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)): Per-invoice reminder overrides.
  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)
- `sourceType` ([InvoiceSourceType](https://devportal.demo.winkpg.io/docs/api/models/InvoiceSourceType.md)): How this invoice was created. (nullable)
  Values:
  - `Manual`: Manually created by a user.
  - `UsageBilling`: Generated from usage billing data.
  - `RecurringBilling`: Generated from a recurring billing contract.
  - `Api`: Created via API by an external integration.
- `sourceReferenceId` (string): Caller-provided reference. Conditional: When SourceReferenceId is not empty. Max length: 200. (nullable)
- `notes` (array<[EntityNote](https://devportal.demo.winkpg.io/docs/api/models/EntityNote.md)>): Internal notes (not shown to recipient). (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): Shown on the invoice to the recipient. Conditional: When RecipientNote is not empty. Max length: 2000. (nullable)
- `footerText` (string): Terms and conditions text. Conditional: When FooterText is not empty. Max length: 5000. (nullable)
- `lineItems` (array<[InvoiceLineItemInputDto](https://devportal.demo.winkpg.io/docs/api/models/InvoiceLineItemInputDto.md)>): Line items to set on the 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. (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)
- `billerSnapshot` ([InvoicePartySnapshotDto](https://devportal.demo.winkpg.io/docs/api/models/InvoicePartySnapshotDto.md)): Optional biller snapshot to freeze on this invoice at creation time.  When supplied, overrides the empty-placeholder default used by IssueAsync.  Useful for programmatic/system-generated invoices where the caller already  holds the party's display info (e.g., billing-run invoice generation).
  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)): Optional recipient snapshot to freeze on this invoice at creation 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)
- `billerId` (string(uuid)) required: The billing entity ID.
- `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.