Invoices

Create and send invoices from your products, exactly like the dashboard’s Invoices page. An invoice starts as a draft; sending it creates a one-time payment link, emails the customer a branded invoice with a PDF attached, and marks it sent. When the customer pays through the hosted invoice it flips to paid and payment.completed fires for the underlying charge. Invoices are sandbox-aware: a test key only sees and creates sandbox invoices. Line items reference products in your workspace: one_time products use their catalog price unless the line passes unit_price (cents), open_ended products require it. The unit price on the invoice is what the hosted checkout charges, even if the product’s price changes later.

Create an invoice

Create a draft invoice. Nothing is emailed until you send it, or pass send: true to create and send in one call.

POSThttps://paysio.com/api/v1/invoices

Authorizations

Authorizationstringheaderrequired

Secret key (sk_*). Prepend your key with Bearer, e.g. Bearer sk_test_your_secret_key.

Body

customer_emailstringrequired

Required unless customer_id is given. The customer is found by email or created.

customer_idstring

Bill an existing customer; its email on file is used when customer_email is omitted.

customer_namestring

Shown on the invoice; used when creating the customer.

itemsarrayrequired

[{ "product_id": "uuid", "quantity": 2, "unit_price": 1500 }]. unit_price (cents) is required for open_ended products and an optional rate override for one_time ones; the hosted checkout charges exactly the unit price on the invoice.

discount_codestring

A workspace discount code. Rejected if it applies to none of the lines.

memostring

Free text shown on the invoice and PDF.

descriptorstring

Statement descriptor override.

due_datestring

ISO 8601 date.

sendboolean

Create and send in one call (default false).

Example request — cURL

curl -X POST https://paysio.com/api/v1/invoices \
  -H "Authorization: Bearer sk_test_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
  "customer_email": "...",
  "items": []
}'

Example request — JavaScript

const res = await fetch("https://paysio.com/api/v1/invoices", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_test_your_secret_key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "customer_email": "...",
    "items": []
  }),
})
const data = await res.json()

Example response (200)

{
  "data": {
    "object": "invoice",
    "id": "b858cb91-7521-44a0-b097-94f6a8ee8d5d",
    "invoiceNumber": 19,
    "invoiceLabel": "INV-00019",
    "status": "draft",
    "customerId": "3c93c21b-5074-478e-bed0-c112d4dfdfee",
    "customerEmail": "[email protected]",
    "customerName": "Buyer Test",
    "items": [
      { "productId": "2be7fe41-3954-4ed8-a119-736827a8734c", "productName": "Pro Plan", "quantity": 2, "unitPrice": 1500, "currency": "USD" }
    ],
    "subtotal": 3000,
    "taxAmount": 0,
    "discountCode": null,
    "discountAmount": 0,
    "amount": 3000,
    "currency": "USD",
    "dueDate": "2026-09-15T00:00:00.000Z",
    "memo": null,
    "hosted_invoice_url": "https://paysio.com/invoice/<token>",
    "pay_url": null,
    "sentAt": null,
    "paidAt": null,
    "transactionId": null,
    "sandbox": false,
    "createdAt": "2026-08-28T18:00:00.000Z"
  }
}

Example response (400)

{
  "error": "Invalid request parameters",
  "type": "invalid_request_error",
  "code": "parameter_invalid"
}

Example response (401)

{
  "error": "Invalid API key provided",
  "type": "authentication_error",
  "code": "api_key_invalid"
}

Example response (429)

{
  "error": "Too many requests",
  "type": "rate_limit_error",
  "code": "rate_limited"
}

List invoices

List invoices, newest first.

GEThttps://paysio.com/api/v1/invoices

Authorizations

Authorizationstringheaderrequired

Any API key. Prepend your key with Bearer, e.g. Bearer sk_test_your_secret_key.

Query parameters

limitinteger

1-100, default 10

starting_afterstring

Cursor for pagination

statusstring

draft, sent, viewed, processing (Debit & Payouts payment settling), paid or void

customer_idstring

Only invoices for one customer

Example request — cURL

curl -X GET https://paysio.com/api/v1/invoices \
  -H "Authorization: Bearer sk_test_your_secret_key"

Example request — JavaScript

const res = await fetch("https://paysio.com/api/v1/invoices", {
  method: "GET",
  headers: {
    "Authorization": "Bearer sk_test_your_secret_key"
  },
})
const data = await res.json()

Example response (200)

{
  "data": [
    {
    "object": "invoice",
    "id": "b858cb91-7521-44a0-b097-94f6a8ee8d5d",
    "invoiceNumber": 19,
    "invoiceLabel": "INV-00019",
    "status": "draft",
    "customerId": "3c93c21b-5074-478e-bed0-c112d4dfdfee",
    "customerEmail": "[email protected]",
    "customerName": "Buyer Test",
    "items": [
      { "productId": "2be7fe41-3954-4ed8-a119-736827a8734c", "productName": "Pro Plan", "quantity": 2, "unitPrice": 1500, "currency": "USD" }
    ],
    "subtotal": 3000,
    "taxAmount": 0,
    "discountCode": null,
    "discountAmount": 0,
    "amount": 3000,
    "currency": "USD",
    "dueDate": "2026-09-15T00:00:00.000Z",
    "memo": null,
    "hosted_invoice_url": "https://paysio.com/invoice/<token>",
    "pay_url": null,
    "sentAt": null,
    "paidAt": null,
    "transactionId": null,
    "sandbox": false,
    "createdAt": "2026-08-28T18:00:00.000Z"
  }
  ],
  "has_more": false
}

Example response (400)

{
  "error": "Invalid request parameters",
  "type": "invalid_request_error",
  "code": "parameter_invalid"
}

Example response (401)

{
  "error": "Invalid API key provided",
  "type": "authentication_error",
  "code": "api_key_invalid"
}

Example response (429)

{
  "error": "Too many requests",
  "type": "rate_limit_error",
  "code": "rate_limited"
}

Retrieve an invoice

Retrieve an invoice. Includes hosted_invoice_url and, once sent, pay_url.

GEThttps://paysio.com/api/v1/invoices/:id

Authorizations

Authorizationstringheaderrequired

Any API key. Prepend your key with Bearer, e.g. Bearer sk_test_your_secret_key.

Example request — cURL

curl -X GET https://paysio.com/api/v1/invoices/:id \
  -H "Authorization: Bearer sk_test_your_secret_key"

Example request — JavaScript

const res = await fetch("https://paysio.com/api/v1/invoices/:id", {
  method: "GET",
  headers: {
    "Authorization": "Bearer sk_test_your_secret_key"
  },
})
const data = await res.json()

Example response (200)

{
  "data": {
    "object": "invoice",
    "id": "b858cb91-7521-44a0-b097-94f6a8ee8d5d",
    "invoiceNumber": 19,
    "invoiceLabel": "INV-00019",
    "status": "draft",
    "customerId": "3c93c21b-5074-478e-bed0-c112d4dfdfee",
    "customerEmail": "[email protected]",
    "customerName": "Buyer Test",
    "items": [
      { "productId": "2be7fe41-3954-4ed8-a119-736827a8734c", "productName": "Pro Plan", "quantity": 2, "unitPrice": 1500, "currency": "USD" }
    ],
    "subtotal": 3000,
    "taxAmount": 0,
    "discountCode": null,
    "discountAmount": 0,
    "amount": 3000,
    "currency": "USD",
    "dueDate": "2026-09-15T00:00:00.000Z",
    "memo": null,
    "hosted_invoice_url": "https://paysio.com/invoice/<token>",
    "pay_url": null,
    "sentAt": null,
    "paidAt": null,
    "transactionId": null,
    "sandbox": false,
    "createdAt": "2026-08-28T18:00:00.000Z"
  }
}

Example response (401)

{
  "error": "Invalid API key provided",
  "type": "authentication_error",
  "code": "api_key_invalid"
}

Example response (404)

{
  "error": "Resource not found",
  "type": "not_found_error",
  "code": "resource_missing"
}

Example response (429)

{
  "error": "Too many requests",
  "type": "rate_limit_error",
  "code": "rate_limited"
}

Send an invoice

Create the payment link (first send only), email the invoice with the PDF attached, and mark it sent. Re-sending emails again and reuses the link. emailed is false when the platform has no outbound email configured.

POSThttps://paysio.com/api/v1/invoices/:id/send

Authorizations

Authorizationstringheaderrequired

Secret key (sk_*). Prepend your key with Bearer, e.g. Bearer sk_test_your_secret_key.

Example request — cURL

curl -X POST https://paysio.com/api/v1/invoices/:id/send \
  -H "Authorization: Bearer sk_test_your_secret_key"

Example request — JavaScript

const res = await fetch("https://paysio.com/api/v1/invoices/:id/send", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_test_your_secret_key"
  },
})
const data = await res.json()

Example response (200)

{
  "data": {
    "object": "invoice",
    "id": "b858cb91-7521-44a0-b097-94f6a8ee8d5d",
    "invoiceLabel": "INV-00019",
    "status": "sent",
    "hosted_invoice_url": "https://paysio.com/invoice/<token>",
    "pay_url": "https://paysio.com/pay/inv-ncMf4kRm6rTgQSHy",
    "emailed": true,
    "sentAt": "2026-08-28T18:05:00.000Z"
  }
}

Example response (401)

{
  "error": "Invalid API key provided",
  "type": "authentication_error",
  "code": "api_key_invalid"
}

Example response (404)

{
  "error": "Resource not found",
  "type": "not_found_error",
  "code": "resource_missing"
}

Example response (429)

{
  "error": "Too many requests",
  "type": "rate_limit_error",
  "code": "rate_limited"
}

Void an invoice

Void an unpaid invoice and deactivate its payment link. Paid invoices cannot be voided.

POSThttps://paysio.com/api/v1/invoices/:id/void

Authorizations

Authorizationstringheaderrequired

Secret key (sk_*). Prepend your key with Bearer, e.g. Bearer sk_test_your_secret_key.

Example request — cURL

curl -X POST https://paysio.com/api/v1/invoices/:id/void \
  -H "Authorization: Bearer sk_test_your_secret_key"

Example request — JavaScript

const res = await fetch("https://paysio.com/api/v1/invoices/:id/void", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_test_your_secret_key"
  },
})
const data = await res.json()

Example response (200)

{
  "data": { "object": "invoice", "id": "b858cb91-7521-44a0-b097-94f6a8ee8d5d", "invoiceLabel": "INV-00019", "status": "void" }
}

Example response (401)

{
  "error": "Invalid API key provided",
  "type": "authentication_error",
  "code": "api_key_invalid"
}

Example response (404)

{
  "error": "Resource not found",
  "type": "not_found_error",
  "code": "resource_missing"
}

Example response (429)

{
  "error": "Too many requests",
  "type": "rate_limit_error",
  "code": "rate_limited"
}