# InvoiceUpdateDto

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 updating a draft invoice. Only allowed when the invoice is not locked.

## Fields
- `recipientId` (string(uuid)) required: Recipient entity ID.
- `recipientType` ([InvoicePartyType](https://devportal.signapay-sbx.winkpg.io/docs/api/models/InvoicePartyType.md)): The type of party `recipientId` names. Always send it. A create that leaves it out binds `GatewayOwner`; when `recipientId` names a customer of the billing merchant, a merchant, or a reseller you can read, that party's type is stored instead. An update does not change the recipient an invoice was created with.
  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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.winkpg.io/docs/api/models/VaultRestriction.md)): Whether new or saved payment methods are allowed on this invoice's payment link. The value is carried onto the hosted payment page session, which doesn't enforce it: the page shows no saved-card picker, and no value removes new card entry where the page accepts cards. (nullable)
  Values:
  - `Any`: No restriction. The payment session carries no vault directive.
  - `AllowNewAndSaved`: Allow both new and saved payment methods. The hosted payment page shows no saved-card picker, so this value behaves like Any there.
  - `SavedOnly`: Only allow previously saved (vaulted) payment methods. Carried onto the payment session but not enforced: where the hosted payment page accepts cards, it still offers new card entry.
- `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.signapay-sbx.winkpg.io/docs/api/models/InvoiceDiscountDto.md)): Invoice-level discount.
  Fields:
  - `type` ([DiscountType](https://devportal.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.winkpg.io/docs/api/models/InvoicePartySnapshotDto.md)): Optional biller snapshot to freeze on this invoice when it is issued. Any field you supply is kept as sent; a field you leave blank is filled at issue from the biller's record on file, where you can read that record. Supply it when the invoice should show something other than the record, such as a remittance address.
  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.signapay-sbx.winkpg.io/docs/api/models/InvoicePartySnapshotDto.md)): Optional recipient snapshot to freeze on this invoice when it is issued. Any field you supply is kept as sent; a field you leave blank is filled at issue from the recipient's record on file (a customer of the billing merchant, a merchant, or a reseller you can read). The Send email goes to this snapshot's email address.
  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)
- `concurrencyStamp` (string): (nullable)

## See also

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