# InvoiceDto

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

Full read DTO for an invoice, including all embedded collections.

## Fields
- `extraProperties` (object): (nullable, read only)
- `id` (string(uuid))
- `creationTime` (string(date-time)): The date and time when this entity was created.
- `creatorId` (string(uuid)): The ID of the user who created this entity. (nullable)
- `lastModificationTime` (string(date-time)): The date and time when this entity was last modified. (nullable)
- `lastModifierId` (string(uuid)): The ID of the user who last modified this entity. (nullable)
- `isDeleted` (boolean): Indicates whether this entity has been deleted.
- `deleterId` (string(uuid)): The ID of the user who deleted this entity, if it is deleted. (nullable)
- `deletionTime` (string(date-time)): The date and time when this entity was deleted, if it is deleted. (nullable)
- `tenantId` (string(uuid)): (nullable)
- `billerId` (string(uuid))
- `billerType` ([InvoicePartyType](https://devportal.demo.winkpg.io/docs/api/models/InvoicePartyType.md)): Identifies the type of entity acting as the biller or recipient on an invoice.
  Values:
  - `GatewayOwner`: Platform-level gateway owner.
  - `Reseller`: Reseller entity.
  - `Merchant`: Merchant entity.
  - `Customer`: End customer.
- `recipientId` (string(uuid))
- `recipientType` ([InvoicePartyType](https://devportal.demo.winkpg.io/docs/api/models/InvoicePartyType.md)): Identifies the type of entity acting as the biller or recipient on an invoice.
  Values:
  - `GatewayOwner`: Platform-level gateway owner.
  - `Reseller`: Reseller entity.
  - `Merchant`: Merchant entity.
  - `Customer`: End customer.
- `invoiceNumber` (string): (nullable)
- `status` ([InvoiceStatus](https://devportal.demo.winkpg.io/docs/api/models/InvoiceStatus.md)): Represents the lifecycle status of an invoice.
  Values:
  - `Draft`: Created, editable, not yet issued.
  - `Issued`: Locked and immutable from this point forward.
  - `Sent`: Delivered to recipient via a notification channel.
  - `Viewed`: Recipient opened/viewed the invoice.
  - `PartiallyPaid`: Some payments applied, balance remaining.
  - `Paid`: Fully paid (balance = 0).
  - `PastDue`: Due date passed with outstanding balance.
  - `Closed`: Manually closed (write-off).
  - `Uncollectible`: Auto-marked after dunning period exhausted (configurable: 30/60/90 days past due).
  - `Cancelled`: Voided (only from Draft).
  - `Refunded`: Full refund issued.
- `isLocked` (boolean): (nullable)
- `billerSnapshot` ([InvoicePartySnapshotDto](https://devportal.demo.winkpg.io/docs/api/models/InvoicePartySnapshotDto.md)): Read DTO for denormalized biller/recipient info frozen at invoice issuance.
  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)): Read DTO for denormalized biller/recipient info frozen at invoice issuance.
  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)
- `currency` (string): (nullable)
- `subtotal` (number(double)): (nullable)
- `taxTotal` (number(double)): (nullable)
- `discountTotal` (number(double)): (nullable)
- `grandTotal` (number(double)): (nullable)
- `amountPaid` (number(double)): (nullable)
- `balanceDue` (number(double)): (nullable)
- `invoiceLevelDiscount` ([InvoiceDiscountDto](https://devportal.demo.winkpg.io/docs/api/models/InvoiceDiscountDto.md)): DTO for an 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)
- `issueDate` (string(date-time)): (nullable)
- `dueDate` (string(date-time)): (nullable)
- `sentAt` (string(date-time)): (nullable)
- `viewedAt` (string(date-time)): (nullable)
- `paidAt` (string(date-time)): (nullable)
- `paymentTermsValue` ([PaymentTerms](https://devportal.demo.winkpg.io/docs/api/models/PaymentTerms.md)): (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)): (nullable)
- `allowPartialPayment` (boolean): (nullable)
- `minimumPaymentAmount` (number(double)): (nullable)
- `partialPaymentTolerance` (number(double)): (nullable)
- `allowedPaymentMethods` (array<string>): (nullable)
- `vaultRestriction` ([VaultRestriction](https://devportal.demo.winkpg.io/docs/api/models/VaultRestriction.md)): (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.  `null` inherits the merchant and feature decision. `true` applies the fee only  when invoice convenience fees are enabled for the tenant. (nullable)
- `depositRequest` ([InvoiceDepositRequestInfoDto](https://devportal.demo.winkpg.io/docs/api/models/InvoiceDepositRequestInfoDto.md)): The deposit request on this invoice, if any. Null when no deposit was requested.
  Fields:
  - `depositType` ([InvoiceDepositType](https://devportal.demo.winkpg.io/docs/api/models/InvoiceDepositType.md)): Whether the deposit is a percentage of the total or a fixed amount.
    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 configured percentage (e.g. 25 for 25%) or fixed amount.
  - `depositAmount` (number(double)): The resolved absolute deposit amount (rounded to the cent).
  - `depositDueDate` (string(date-time)): When the deposit is due; null when due on receipt with the invoice. (nullable)
  - `isSatisfied` (boolean): True once the deposit has been fully collected.
- `hppPageId` (string(uuid)): (nullable)
- `templateId` (string(uuid)): (nullable)
- `sourceType` ([InvoiceSourceType](https://devportal.demo.winkpg.io/docs/api/models/InvoiceSourceType.md)): (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): (nullable)
- `notes` (array<[EntityNote](https://devportal.demo.winkpg.io/docs/api/models/EntityNote.md)>): (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): (nullable)
- `footerText` (string): (nullable)
- `reminderConfig` ([InvoiceReminderConfigDto](https://devportal.demo.winkpg.io/docs/api/models/InvoiceReminderConfigDto.md)): DTO for invoice reminder configuration. Each member overrides the tenant's reminder default on its  own; a member that is null or omitted inherits that default.
  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)
- `lineItems` (array<[InvoiceLineItemDto](https://devportal.demo.winkpg.io/docs/api/models/InvoiceLineItemDto.md)>): (nullable)
  Fields of each item:
  - `id` (string(uuid)): Stable identity for update/delete operations.
  - `sortOrder` (integer(int32)): Display order on the invoice.
  - `parentLineItemId` (string(uuid)): Parent line item ID for bundle/discount/tax line hierarchies. (nullable)
  - `name` (string): Product name snapshot (formal product name). (nullable)
  - `description` (string): Line item description shown on PDF and HPP. (nullable)
  - `notes` (string): Per-line notes visible to the biller only. (nullable)
  - `productId` (string(uuid)): Optional link to the product catalog. (nullable)
  - `productCode` (string): SKU or product code. (nullable)
  - `unitOfMeasure` (string): Unit of measure (e.g., "each", "hour", "GB"). (nullable)
  - `commodityCode` (string): Commodity code sent as enhanced (Level 3) card data when the invoice is paid by card. At most  25 characters. (nullable)
  - `quantity` (number(double)): Quantity.
  - `unitPrice` (number(double)): Unit price.
  - `grossAmount` (number(double)): Computed: Quantity * UnitPrice.
  - `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)
  - `discountAmount` (number(double)): Resolved discount amount. (nullable)
  - `netAmount` (number(double)): After discount, before tax.
  - `taxRateId` (string(uuid)): Reference to a reusable tax rate definition. (nullable)
  - `taxRatePercent` (number(double)): Snapshot of the tax rate percentage. (nullable)
  - `taxableAmount` (number(double)): Explicit taxable base amount. (nullable)
  - `taxAmount` (number(double)): Computed tax amount.
  - `taxJurisdiction` (string): Tax jurisdiction (state/country). (nullable)
  - `taxRateSource` ([InvoiceTaxRateSource](https://devportal.demo.winkpg.io/docs/api/models/InvoiceTaxRateSource.md)): Where `taxRatePercent` came from. Always populated on read: a line stored before  provenance existed reads as Catalog when it names a `taxRateId`, otherwise Manual. (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): The tax provider that sourced the percentage, when `taxRateSource` is Provider. (nullable)
  - `taxCode` (string): Tax code snapshotted from product or overridden. (nullable)
  - `isTaxable` (boolean): Whether tax applies to this line. (nullable)
  - `lineTotal` (number(double)): Line total including tax.
  - `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)
  - `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)
- `payments` (array<[InvoicePaymentDto](https://devportal.demo.winkpg.io/docs/api/models/InvoicePaymentDto.md)>): (nullable)
  Fields of each item:
  - `id` (string(uuid))
  - `transactionId` (string(uuid)): (nullable)
  - `amount` (number(double)): The amount applied against the invoice balance: the invoiced base, never a fee-inclusive  total. Fees the payer was charged on top ride the members below.
  - `convenienceFeeAmount` (number(double)): The convenience fee charged on top of `amount`, in the invoice currency, when one was  assessed. (nullable)
  - `surchargeAmount` (number(double)): The credit-card surcharge charged on top of `amount`, in the invoice currency, when one  was assessed. (nullable)
  - `chargedTotal` (number(double)): The total the payer was actually charged, when known. (nullable)
  - `paymentMethod` (string): (nullable)
  - `status` ([InvoicePaymentStatus](https://devportal.demo.winkpg.io/docs/api/models/InvoicePaymentStatus.md)): Status of a payment attempt against an invoice.
    Values:
    - `Pending`: Payment is pending processing.
    - `Succeeded`: Payment succeeded.
    - `Declined`: Payment was declined by the processor.
    - `Returned`: Payment was returned (e.g., ACH return).
    - `Refunded`: Payment was refunded.
    - `Indeterminate`: The attempt reached the processor but produced no answer the invoice can act on: a referral the merchant has to resolve by voice, a pending or submitted authorization, a partial approval whose approved base cannot be derived, or a status the platform does not recognize. Nothing is credited against the balance and the attempt is not a decline; the row exists so the invoice shows that someone tried and what came back.
  - `declineReasonCode` (string): (nullable)
  - `appliedAt` (string(date-time))
  - `notes` (string): (nullable)
  - `recordedBy` (string): (nullable)
- `activities` (array<[InvoiceActivityDto](https://devportal.demo.winkpg.io/docs/api/models/InvoiceActivityDto.md)>): (nullable)
  Fields of each item:
  - `id` (string(uuid))
  - `timestamp` (string(date-time))
  - `type` ([InvoiceActivityType](https://devportal.demo.winkpg.io/docs/api/models/InvoiceActivityType.md)): Classifies entries in the invoice activity timeline.
    Values:
    - `Created`: Invoice was created.
    - `Sent`: Invoice was sent to the recipient.
    - `Viewed`: Recipient viewed the invoice.
    - `PaymentReceived`: A payment was received.
    - `PaymentDeclined`: A payment attempt was declined.
    - `ReminderSent`: A reminder was sent.
    - `StatusChanged`: Invoice status changed.
    - `Edited`: Invoice was edited (Draft only).
    - `Closed`: Invoice was closed.
    - `Cancelled`: Invoice was cancelled.
    - `Refunded`: Invoice was refunded.
    - `CreditApplied`: A credit note was applied.
    - `NoteAdded`: An internal note was added.
    - `AutoChargeAttempted`: An automatic payment was attempted (auto-charge or smart-retry).
    - `PaymentRetryScheduled`: A soft-declined automatic payment was scheduled for a retry.
    - `PaymentRetriesExhausted`: Smart-retry attempts were exhausted (max attempts or retry window reached).
    - `PaymentRetriesStopped`: Smart-retry attempts were stopped (hard decline or manual intervention).
    - `PaymentPlanStarted`: A payment plan was set up against the invoice balance.
    - `InstallmentCollected`: An installment was collected (manually recorded or auto-charged).
    - `InstallmentCollectionFailed`: An automatic installment collection attempt failed (declined).
    - `PaymentPlanCancelled`: The payment plan was cancelled before all installments were collected.
    - `PaymentIndeterminate`: A payment attempt came back with a result the invoice cannot act on (a referral, a pending or submitted authorization, a partial approval, or an unrecognized status). Nothing was credited. Appended last: the numeric value is stored on the activity row and must never be renumbered.
    - `PaymentLinkReissued`: An operator replaced the payment link with a fresh one without notifying the recipient. The previous link stopped working. Appended last: the numeric value is stored on the activity row and must never be renumbered.
  - `description` (string): (nullable)
  - `userId` (string(uuid)): (nullable)
  - `metadata` (string): (nullable)
- `customFields` (array<[CustomFieldValueDto](https://devportal.demo.winkpg.io/docs/api/models/CustomFieldValueDto.md)>): (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)
- `concurrencyStamp` (string): (nullable)
- `entityVersion` (integer(int32))

## See also

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