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:

  1. Show the users on your platform which payment corresponds to which invoice
  2. Present the correct invoice references on checkout pages
  3. 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 nameIs RequiredTypeDescription
currencyYesISO 4217The currency of the invoice
totalAmountYesNumberThe total invoice amount
referenceYesStringThe invoice number on your system.
batchIdNoStringThe id of the batch that this invoice was included in
vatAmountYesNumberThe total VAT amount for the invoice. (can be 0)
publicUrlNoStringA public URL to the invoice PDF version
dueDateNoDateThe invoice due date
lineItemsYesan array of lineItemLine item object
CustomerYesObjectContains the following fields id, email, phone
paymentStatusYesStringCurrent invoice payment status (Paid, partially paid, etc...)
invoiceObjectYesObjectYour invoice object
isRecurringYesBooleanIndicates if this invoice is a recurring invoice

The following table includes lineItem object array:

Field nameIs RequiredTypeDescription
descriptionYesStringA description for a specific line item
amountYesNumberA price of a unit for a specific line item
quantityYesNumberThe 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
}