Invoice endpoint
What is the goal of invoice endpoint?
The invoices endpoint allows platforms to update UNIPaaS about every invoice that is created or updated by users on the platform. Updating UNIPaaS about every invoice created on your platform is critical for UNIPaaS to connect between invoices and transactions.
UNIPaaS will use invoice information for the following:
- Show the users on your platform which payment corresponds to which invoice
- Present the correct invoice references on checkout pages
- Enable relevant payment methods for recurring vs. single invoices
When should you use the invoice endpoint?
We strongly suggest posting every invoice created on your platform to UNIPaaS automatically, at the moment it is created or uploaded by your user.
We also suggest using the PATCH function to update existing invoices once users update them on your platform.
This integration will ensure UNIPaaS is able to connect between payments and invoices, and provide your user with valuable information for their reconciliation.
The invoice object
The following table includes the invoice object fields:
Field name | Is Required | Type | Description |
---|---|---|---|
currency | Yes | ISO 4217 | The currency of the invoice |
totalAmount | Yes | Number | The total invoice amount |
reference | Yes | String | The invoice number on your system. |
batchId | No | String | The id of the batch that this invoice was included in |
vatAmount | Yes | Number | The total VAT amount for the invoice. (can be 0) |
publicUrl | No | String | A public URL to the invoice PDF version |
dueDate | No | Date | The invoice due date |
lineItems | Yes | an array of lineItem | Line item object |
Customer | Yes | Object | Contains the following fields id , email , phone |
paymentStatus | Yes | String | Current invoice payment status (Paid, partially paid, etc...) |
invoiceObject | Yes | Object | Your invoice object |
isRecurring | Yes | Boolean | Indicates if this invoice is a recurring invoice |
The following table includes lineItem
object array:
Field name | Is Required | Type | Description |
---|---|---|---|
description | Yes | String | A description for a specific line item |
amount | Yes | Number | A price of a unit for a specific line item |
quantity | Yes | Number | The quantity of a unit for a specific line item |
Using the invoice endpoint
For every invoices created by a user on your platform, use the following endpoint to POST the invoice to UNIPaaS.
POST/platform/vendors/{vendorId}/invoices
{
"currency": "GBP",
"totalAmount": 99.5,
"reference": "INV-1234",
"vatAmount": 19.9,
"batchId": "bt4874583",
"publicUrl": "http://yourcompany.com/invoice.pdf",
"dueDate": "2022-12-12T08:42:52.933Z",
"paymentStatus": "unpaid",
"lineItems": [
{
"description": "line 1",
"unitPrice": 10.6,
"quantity": 3
},
{
"description": "line 2",
"unitPrice": 19.3,
"quantity": 1
}
],
"invoiceObject": {},
"isRecurring": false,
"customer": {
"id": "1234",
"email": "[email protected]",
"phone": "+447975777666"
}
}
Response example:
{
"id": "6391fd42a38e34b15b118d9b", //Used to identify this invoice in UNIPaaS
"vendorId": "6384b75fc661567cd8b337b5",
"merchantId": "6384b75fc66156798567898a",
"currency": "GBP",
"totalAmount": 99.5,
"vatAmount": 19.9,
"reference": "INV-123456",
"publicUrl": "http://yourcompany.com/invoice.pdf",
"lineItems": [
{
"description": "line 1",
"unitPrice": 10.6,
"quantity": 3
},
{
"description": "line 2",
"unitPrice": 19.3,
"quantity": 1
}
],
"invoiceObject": {},
"isRecurring": false,
"customer": {
"id": "1234",
"email": "[email protected]",
"phone": "+447975777666"
},
"paymentStatus": "unpaid",
"dueDate": "2022-12-12T08:42:52.954Z",
"createdAt": "2022-12-12T08:42:52.954Z",
"updatedAt": "2022-12-12T08:42:52.954Z"
}
To update an existing invoice, use PATCH/platform/vendors/{vendorId}/invoices/{invoicesId}
{
"id": "6391fd42a38e34b15b118d9b", //Used to identify this invoice in UNIPaaS
"merchantId": "624c567dfcb8145744c7a881",
"vendorId": "638498e2c661567cd8b337b3",
"currency": "GBP",
"totalAmount": 99.5,
"vatAmount": 12.23,
"reference": "INV-1234",
"publicUrl": "http://yourcompany.com/invoice.pdf",
"invoiceObject": {},
"customer": {
"id": "1234",
"email": "[email protected]",
"phone": "+447975777666"
},
"lineItems": [
{
"description": "line 1",
"unitPrice": 10.6,
"quantity": 3
},
{
"description": "line 2",
"unitPrice": 19.3,
"quantity": 1
}
],
"paymentStatus": "unpaid",
"dueDate": "2022-12-12T08:47:25.450Z",
"createdAt": "2022-12-12T08:42:26.108Z",
"updatedAt": "2022-12-12T08:42:26.108Z",
"correlationId": "e566a2a8-ddf7-4400-99e9-102ee39855df",
"isRecurring": false
}
Updated about 2 hours ago