Create Invoice

Create invoice endpoint helps you create a new invoice. Invoices are always created in DRAFT status

Header Parameters

token*string

Authentication token generated using the API Key and Secret Key using an Merchant Account. Required for all API requests.

Idempotency-Key?string

A Unique key generated for each operation to prevent duplicate processing when retrying requests. A UUID is recommended. The key must contain 1–255 visible ASCII characters. If the same request is retried with the same key within 24 hours, the API returns the original successful response with the header Idempotent-Replayed: true instead of processing the operation again

Request Body

customer_id*string

ID of the customer the invoice is for. The customer must belong to a store. Also called the Consumer ID; find it in the My Customers module of the iPOSpays merchant portal.

amount*integer

Amount in cents (cash price), e.g. 1050 = $10.50

Range1 <= value <= 100000000

store_id?|

12-character public store ID of an ACTIVE store, from GET /stores

Refer to Get Store ID to find the store ID.

tpn?|

ACTIVE terminal TPN, 12–50 digits

invoice_url*|

HTTPS URL of the invoice document: PDF, PNG or JPG/JPEG (detected from the file content, not the extension). DOC, DOCX, XLSX, XML and other types are rejected. The server downloads the start of it to check the type.

Formaturl

Lengthlength <= 255

Response Body

`application/json`

curl -X POST "https://example.com" \  -H "token: your-access-token-here" \  -H "Idempotency-Key: 8a7c2d91-4e6b-4f03-9c52-1b6d8e5a7f20" \  -H "Content-Type: application/json" \  -d '{    "customer_id": "OGS1AN68JFR6H54",    "amount": 1050,    "store_id": "05cbaac8502f",    "tpn": "",    "invoice_url": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf"  }'

{
  "data": {
    "invoice_number": "2610267125NkqLPJLTT0",
    "customer_id": "AMLZT40Y2STSJYX",
    "amount": 1050,
    "status": "DRAFT",
    "store_id": "8b1523efdd22",
    "tpn": null,
    "invoice_url": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
    "payment_link_status": "NONE",
    "transactions": [],
    "created_at": "2026-10-26T07:01:25.000Z",
    "updated_at": "2026-10-26T07:01:25.000Z"
  },
  "message": "Invoice created successfully",
  "response_code": "SUCCESS",
  "status_code": 201,
  "request_id": "UAT-20261026070125-ZFWLSV",
  "timestamp": "2026-10-26T07:01:25.707Z"
}

{
  "data": null,
  "message": "The request contains invalid input parameters.",
  "response_code": "BAD_REQUEST",
  "status_code": 400,
  "request_id": "TEST-20261022132140--GIYWY",
  "timestamp": "2026-10-22T07:51:40.696Z",
  "errors": [
    {
      "field": "invoice_url",
      "messages": [
        "invoice_url or file is required"
      ]
    }
  ]
}

{
  "data": null,
  "message": "Missing authentication token. Please include a valid API token in your request.",
  "response_code": "TOKEN_MISSING",
  "status_code": 401,
  "request_id": "TEST-20261022075139-57OO8V",
  "timestamp": "2026-10-22T07:51:39.708Z"
}

{
  "data": null,
  "message": "Customer not found",
  "response_code": "NOT_FOUND",
  "status_code": 404,
  "request_id": "TEST-20261022132141-J4QUXE",
  "timestamp": "2026-10-22T07:51:41.670Z"
}

{
  "data": null,
  "message": "Store ID is ambiguous, send tpn instead",
  "response_code": "CONFLICT",
  "status_code": 409,
  "request_id": "TEST-20261009114453-80BZYX",
  "timestamp": "2026-10-09T06:14:53.871Z"
}

{
  "data": null,
  "message": "Store ID and TPN must be from the same store.",
  "response_code": "PRECONDITION_FAILED",
  "status_code": 412,
  "request_id": "<generated per request>",
  "timestamp": "<ISO 8601 time>"
}

{
  "data": null,
  "message": "The request contains invalid input parameters.",
  "response_code": "BAD_REQUEST",
  "status_code": 413,
  "request_id": "TEST-20261022132104-L3OC2G",
  "timestamp": "2026-10-22T07:51:04.770Z",
  "errors": [
    {
      "field": "file",
      "messages": [
        "file is too large (maximum 5 MB)"
      ]
    }
  ]
}

{
  "data": null,
  "message": "Unsupported content type",
  "response_code": "BAD_REQUEST",
  "status_code": 415,
  "request_id": "<generated per request>",
  "timestamp": "<ISO 8601 time>",
  "errors": [
    {
      "field": "body",
      "messages": [
        "Content-Type must be application/json"
      ]
    }
  ]
}

{
  "data": null,
  "message": "This Idempotency-Key was already used with a different request",
  "response_code": "BAD_REQUEST",
  "status_code": 422,
  "request_id": "<generated per request>",
  "timestamp": "<ISO 8601 time>"
}

{
  "data": null,
  "message": "Too many uploads are being processed, please retry shortly",
  "response_code": "RATE_LIMITED",
  "status_code": 429,
  "request_id": "<generated per request>",
  "timestamp": "<ISO 8601 time>"
}

{
  "data": null,
  "message": "An error occurred while processing your request. Please try again later.",
  "response_code": "INTERNAL_ERROR",
  "status_code": 500,
  "request_id": "<generated per request>",
  "timestamp": "<ISO 8601 time>"
}

{
  "data": null,
  "message": "Could not allocate a unique invoice number",
  "response_code": "SERVICE_UNAVAILABLE",
  "status_code": 503,
  "request_id": "<generated per request>",
  "timestamp": "<ISO 8601 time>"
}

Header Parameters

Request Body

Response Body

201application/json

400application/json

401application/json

404application/json

409application/json

412application/json

413application/json

415application/json

422application/json

429application/json

500application/json

503application/json

JSON: invoice_url + store_id

JSON: invoice_url + tpn

invoice_url to a PNG image

invoice_url to a JPG image

invoice_url with HTTPS:// in upper case (accepted, stored as https://)

Upload: PDF file + store_id

Upload: PNG file + tpn

Upload: JPG file

JSON without invoice_url (and no file)

customer_id missing

amount missing

amount with decimals

amount sent as text

amount 0

amount above the maximum

Neither store_id nor tpn

customer_id wrong format

store_id wrong format

invoice_url not HTTPS

invoice_url longer than 255 characters

invoice_url with credentials

invoice_url pointing to a private host

invoice_url that is not a PDF/image

status sent on create

transactions sent on create

Unknown field

customer_id empty

customer_id not a string

amount not a number

amount boolean

amount negative

amount text with leading zero

amount text in exponent form

store_id not a string

tpn wrong format

invoice_url not a string

invoice_url not a URL

transaction_id sent

transaction_amount sent

mark_as_paid sent

mark_as_paid_reason sent

Body is a JSON array

invoice_url to an XML file (not accepted)

invoice_url to a DOCX file (not accepted)

invoice_url to an XLSX file (not accepted)

fileName sent (not a field any more)

Upload: file and invoice_url together

Upload request without file and without invoice_url

Upload: DOCX file (not accepted)

Upload: text content in a file named .pdf

Upload: empty file

Upload: file sent under a field other than "file"

Upload: PDF containing JavaScript

Upload: PDF with more than 100 pages

Upload: corrupt PNG

Upload: amount with decimals

ISO token without storeId or tpn

Idempotency-Key empty, too long or with non-ASCII / space characters

Malformed JSON body

token header missing

store_id of another merchant

Upload without token header

Invalid token

Expired token

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`