# Invoices > For the complete documentation index, see [llms.txt](/llms.txt). Invoices serve as records of the outstanding balances owed by customers and can be generated either on a one-time basis or periodically for subscription-based services. Platforms typically have the capability to autonomously generate invoices for their businesses, or to integrate with accounting software platforms to retrieve invoices from there. Continuous updates on every invoice created by vendors using the payment solution powered by Unipaas are essential. These updates allow us to establish a seamless connection between invoices and transactions on our end, ensuring compliance with regulatory requirements and improved user experience. ## **Benefits of matching invoices to transactions** **Regulatory compliance assurance:** Unipaas uses invoice information to stay compliant with relevant financial regulations and industry standards, ensuring a secure and trustworthy payment environment for both your platform and your customers. **Seamless payment collection with Direct Debit:** Unipaas leverages invoice data to enable smooth and hassle-free payment collection through Direct Debit, streamlining the payment process for users. **Enhanced user experience:** Unipaas aims to clearly display the correlation between payments and corresponding invoices, providing users with enhanced transparency, improved reconciliation and better understanding of their financial activity. **Accurate invoice references at checkout:** Unipaas ensures that checkout pages present the correct and up-to-date invoice references, reducing errors and offering a more reliable payment experience to buyers. **Tailored payment options:** Leveraging the insights from invoice data, Unipaas is able to offer relevant and appropriate payment methods, differentiating between recurring and one-time invoices to meet diverse user needs effectively. # **Invoice endpoint** It is highly recommended to set up automatic forwarding for every invoice to Unipaas whenever it is created or modified on your platform. [Post invoice (one-time or recurring)](/docs/invoices/#post-invoice) [Update invoice](/docs/invoices/#update-invoice) *** # **Post invoice** ## When to use Every time a new invoice is created on your platform. ## How to use [POST/platform/vendors/{vendorId}/invoices](/reference/#tag/vendor/POST/vendors/%7BvendorId%7D/invoices) Posting or updating an invoice can take money If `paymentMethods` contains `directDebit` and `customer.reference` matches a consumer with an active mandate, the invoice schedules a Direct Debit collection immediately - on POST, and equally when `directDebit` is added to an existing invoice via PATCH. No further call is required. A `dueDate` in the past does not prevent this. The collection is scheduled for the earliest permitted date - approximately five working days ahead - regardless of how old the invoice is. A two-year-old due date and a due date of today both schedule for the same day. If you are loading historical invoices, or backfilling from another system, do not send `directDebit` unless you intend to collect those invoices - and do not add `directDebit` to historical invoices via PATCH for the same reason. Check `authorizationId` on the response: if it is populated, a collection has been scheduled. ### The invoice object * JSON ```json { "reference": "INV-1234", "currency": "GBP", "totalAmount": 99.5, "vatAmount": 19.9, "dueDate": "2026-12-12T08:42:52.933Z", "paymentMethods":["directDebit"], "paymentStatus": "unpaid", "totalPaid": 0, "customer": { "reference": "1234", "email": "test@gmail.com", "name": "Kevin Malone" }, "lineItems": [ { "description": "line 1", "unitPrice": 10.6, "quantity": 3 }, { "description": "line 2", "unitPrice": 19.3, "quantity": 1 } ], "isRecurring": true, "subscriptionId": "sub-123", "external":false, "batchId": "batch-777", "publicUrl": "http://yourcompany.com/invoice.pdf", "invoiceObject": {} } ``` **Attributes** | Name | Is Required | Type | Description | | ---------------- | ----------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `reference` | Yes | String | The invoice number on your system. Must be unique per vendor - a duplicate `reference` is rejected with `400`, so a bulk load or a re-run of the same batch will fail on any repeat. | | `currency` | Yes | String | The currency of the invoice. One of `GBP`, `USD`, `EUR`, or `CAD` (case-sensitive - lowercase values such as `gbp` are rejected). | | `totalAmount` | Yes | Number | The total invoice amount | | `vatAmount` | No | Number | The total VAT amount for the invoice (can be 0). If not provided, will be set to 0 by default. | | `dueDate` | Yes | Date | The invoice due date. Use ISO 8601, and for a specific day prefer date-only (`2026-12-12`), which is stored as midnight UTC.Non-ISO slash and dash formats are parsed as **MM/DD/YYYY**, not DD/MM/YYYY - so `01/02/2026` is stored as 2 January, and a genuinely UK-formatted value like `13/01/2026` is rejected with `400`. A UK-formatted extract will therefore part-succeed on the wrong date and part-fail, so always send ISO 8601.A local time with a UTC offset (for example `2026-12-12T23:30:00+13:00`) is converted to UTC, which can shift the stored calendar date - send explicit UTC to avoid this. An invalid calendar date rolls forward rather than erroring: `2026-02-30` is stored as 2 March.For Direct Debit invoices, `dueDate` determines the collection date, subject to a minimum notice period of approximately five working days and adjustment to the next working day. A due date at or inside that window, including one in the past, is clamped to the earliest permitted date rather than rejected (see the warning above). This raises the stakes on the MM/DD parsing above: a misparsed date now moves money rather than just displaying wrongly. | | `totalPaid` | No | Number | The total amount paid so far on this invoice. If not provided, will be set to 0 by default. | | `batchId` | No | String | The ID of the batch that this invoice was included in. | | `publicUrl` | No | String | A public URL to the invoice PDF version. | | `lineItems` | Yes | Array | Line item object - see table below. The key is required, but an empty array (`[]`) is accepted. | | `customer` | Yes | Object | Customer object - see table below. | | `paymentStatus` | Yes | Enum | Current invoice payment status: Unpaid = `unpaid` Paid = `paid` Partially Paid = `partially_paid` Refunded = `refunded` PartiallyRefunded = `partially_refunded` | | `paymentMethods` | No | Array, Enum | States which payment methods will be available for this specific invoice. For `directDebit` this field is also an instruction to collect: sending it against an active mandate schedules a Direct Debit collection when the invoice is posted (see the [warning above](#post-invoice)).Available payment methods: `apm` `bankTransfer` `card` `creditCard` `directDebit` `taxFreeChildcare``directDebit` is only retained when `customer.reference` matches a consumer with an active mandate. If there is no active mandate for that consumer, `directDebit` is silently replaced with the methods configured for your platform and the request still returns `201`.Check the response to see whether money is moving, not just what was stored: `paymentMethods` tells you which methods were kept, and `authorizationId` tells you whether a collection was scheduled (populated) or not (null). | | `invoiceObject` | No | Object | The invoice object in its original form as created on your platform. | | `isRecurring` | Yes | Boolean | Indicates if this invoice is a recurring one. | | `external` | No | Boolean | Indicates if this invoice was paid using external (non Unipaas). payment method. If value is set to 'false' it is an indication that an invoice paid with Unipaas. Default value is set to 'false'. | | `subscriptionId` | No | String | The recurring invoice subscription identifier. | `lineItem` **attributes:** | Name | Is Required | Type | Description | | :------------ | :---------- | :----- | :---------------------------------------------- | | `description` | Yes | String | A description for a specific line item | | `unitPrice` | Yes | Number | The price of a unit for a specific line item | | `quantity` | Yes | Number | The quantity of a unit for a specific line item | `customer` **attributes:** | Name | Is Required | Type | Description | | :---------- | :---------- | :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `reference` | No | String | Platform customer identifier. Optional to the schema, but for Direct Debit to be offered it must match the consumer reference used when the mandate was created. | | `name` | No | String | The customer full name. | | `id` | No | String | Unipaas customer identifier. | | `email` | No | String | The customer email address. | Validation behaviour (applies to both POST and PATCH) * **Types are strict.** Numbers and booleans must be sent as their JSON types, not strings - `"totalAmount": "99.50"` and `"isRecurring": "false"` are both rejected. Watch for this when the source is a CSV or spreadsheet export. * **There is no cross-field validation.** Combinations that do not add up are accepted, for example `paymentStatus: "paid"` with `totalPaid` below `totalAmount`, `totalPaid` greater than `totalAmount`, `vatAmount` greater than `totalAmount`, line items that do not sum to `totalAmount`, and `partially_paid` with `totalPaid: 0`. Your platform is responsible for keeping these consistent. * **Unknown fields are silently ignored.** A misspelled field name returns success and changes nothing, so a typo in a field name does not surface as an error. ### Response example * JSON ```json { "id": "6539271a23ebdaa55bae0e4f", "merchantId": "6440ca5ec6f5484043645595", "vendorId": "64b2acf5e59cc36181291f8d", "currency": "GBP", "totalAmount": 99.5, "totalPaid": 0, "vatAmount": 19.9, "reference": "INV-1234", "publicUrl": "http://yourcompany.com/invoice.pdf", "invoiceObject": {}, "subscriptionId": "sub-123", "isRecurring": true, "batchId": "batch-777", "customer": { "reference": "1234567", "email": "test@gmail.com", "name": "orel reast" }, "lineItems": [ { "description": "line 1", "unitPrice": 10.6, "quantity": 3 }, { "description": "line 2", "unitPrice": 19.3, "quantity": 1 } ], "paymentStatus": "unpaid", "dueDate": "2022-12-12T08:42:52.933Z", "paymentMethods": [ "directDebit" ], "external": false, "authorizationId": "65392719bd672b26f20d53ca", "signedLinkId": "RGJ4_2wLWr", "checkoutLink": "https://dev-checkout.unipaas.com/RGJ4_2wLWr/", "sessionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXJjaGFudElkIjoiNjJmYzk5YjI0YzcyOGIzZjAyZmM2MzRmIiwibWVyY2hhbnROYW1lIjoiTmV3IFBsYXRmb3JtIiwiYW1vdW50IjoxMCwiY3VycmVuY3kiOiJHQlAiLCJlbWFpbCI6InVzZXJAdGVzdC5jb20iLCJjb3VudHJ5IjoiR0IiLCJzZWxsZXJJZCI6IjY1MWU2ODRhZDAwNjg5MWIzNWJkZGQ2OCIsInZlbmRvcklkIjoiNjUxZTY4NGFkMDA2ODkxYjM1YmRkZDY4IiwicGhvbmUiOiIrNDQxNjE0OTYwMjU1Iiwic2NvcGVzIjpbIndlYnNka19hY2Nlc3MiLCJkaXJlY3RfZGViaXRfcmVhZCJdLCJpc1JlY3VycmluZyI6ZmFsc2UsImVudiI6ImxvY2FsIiwicGF5bWVudExpbmtJZCI6Ik0zc09laFU1ZEMiLCJpYXQiOjE3MjcwOTc5NTMsImV4cCI6MTcyNzEwMTU1M30.mR_rA3cF5UTANKHcgPVyyfidXg8JieBg_otX6Iz_5V8", "createdAt": "2023-10-25T14:32:58.566Z", "updatedAt": "2023-10-25T14:32:58.566Z" } ``` | Name | Type | Description | | :---------------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `id` | String | The value you obtained in the response to POST request, serves to identify this invoice in Unipaas | | `authorizationId` | String | Populated when a payment has been initiated for this invoice. For a Direct Debit invoice against an active mandate this is set at creation, and `GET /pay-ins/{authorizationId}` returns the scheduled collection including its `collectionDate`. Null where no payment has been initiated. | | `checkoutLink` | String | The checkout link for the invoice, which includes the available payment methods for buyer. | ### Recurring invoices Report each recurring invoice to the invoice endpoint as it is created, following the instructions provided above, and set `isRecurring` to `true` so it is recorded as recurring. Direct Debit collection depends on an **active mandate on the consumer whose reference matches the invoice's `customer.reference`**. `isRecurring` does not affect this - without a matching active mandate, `directDebit` is dropped from `paymentMethods` regardless of its value. Where that mandate exists and `directDebit` is sent, posting the invoice schedules the collection. You do not need to call `POST /pay-ins` separately for this flow. See the [warning above](#post-invoice) regarding due dates. To set up the mandate, see [Implement Direct Debit via API](/docs/implement-direct-debit-via-api/). *** # Update invoice ## When to use 1. When an existing invoice has been edited, e.g. changes to the total amount or due date. 2. When an existing invoice has been fully or partially paid. Flexible checkout modifications require the mandatory use of the PATCH request If not implemented, vendors won't be able to make adjustments to the amount, due date, or invoice payment method The following invoice parameters might affect the payment: * `totalAmount` * `totalPaid` * `paymentMethods` * `paymentStatus` * `dueDate` Updating an invoice with a scheduled Direct Debit collection While a collection is `Scheduled`, these fields drive it live: * `paymentMethods` - adding `directDebit` schedules a collection. Removing it voids a scheduled one, which is how to cancel a collection you did not intend. * `dueDate` - reschedules the collection, subject to the same minimum notice period and working-day adjustment. Note the MM/DD parsing described under `dueDate` above applies here too, so a non-ISO date will move a live collection to the wrong day. * `totalAmount` - changes the amount to be collected. Check `authorizationId` on the response and `GET /pay-ins/{authorizationId}` to confirm the resulting state. ## How to use [PATCH/vendors/{vendorId}/invoices/{invoiceId}](/reference/#tag/vendor/PATCH/vendors/%7BvendorId%7D/invoices/%7BinvoicesId%7D) ### The updated invoice object example You may only update the values that have been changed. In this example, the invoice was subject to a partial payment of 60 GBP, leading to a change in the payment status, and the payment method was switched by user to Direct Debit. * JSON ```json { "id": "6391fd42a38e34b15b118d9b", "totalPaid": 60.0, "paymentStatus": "partially_paid", "paymentMethods":["directDebit"] } ``` **Attributes** | Name | Is Required | Type | Description | | ---------------- | ----------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | No | String | Ignored. The invoice to update is identified solely by the `invoiceId` in the path; a value sent in the body (or omitted entirely) has no effect. | | `reference` | No | String | The invoice number on your system. Mutable via PATCH. The per-vendor uniqueness constraint still applies, so a rename that collides with another invoice's `reference` is rejected. | | `totalPaid` | No | Number | The total amount paid so far on this invoice | | `totalAmount` | No | Number | The total invoice amount. Where a Direct Debit collection is scheduled, this changes the amount to be collected. | | `dueDate` | No | Date | The invoice due date. Where a Direct Debit collection is scheduled, this reschedules it. Same format rules as on POST. | | `paymentStatus` | No | Enum | Current invoice payment status | | `paymentMethods` | No | Array, Enum | States which payment methods will be available for this specific invoice.Available payment methods: `apm` `bankTransfer` `card` `creditCard` `directDebit` `taxFreeChildcare`As on POST, `directDebit` is only retained when the invoice's `customer.reference` matches a consumer with an active mandate. | | `lineItems` | No | Array | Replaces the existing line items **wholesale** - it does not merge. Sending a single line item discards any items already on the invoice, so always send the full set. | Note **The response body for a PATCH request is the same as for a POST request. The status code differs: PATCH returns `200`, whereas POST returns `201`.**