Invoices

Create an invoice

Creates an ad-hoc invoice for a customer. Callers can supply line items, a billing period, purchase order number, and an initial status (draft or issued). Requesting issued releases the invoice for issuance, which completes asynchronously — the response returns the invoice in processing and it settles to issued shortly after, observable via the Get Invoice endpoint. Alternatively, pass tax_calculation_id to turn a persisted tax calculation into an invoice: its line items, tax, and buyer are pinned and the invoice is issued synchronously; add a payment and status: paid to record settlement and mark it paid in the same call.

POST

invoices

Create an invoice

curl --request POST \
  --url https://api.alguna.io/invoices \
  --header 'Alguna-Version: <alguna-version>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "autopay_timing": "on_due_date",
  "billing_period_end": "2026-02-01T00:00:00Z",
  "billing_period_start": "2026-01-01T00:00:00Z",
  "currency": "USD",
  "customer_id": "<string>",
  "description": "<string>",
  "issue_date": "2023-11-07T05:31:56Z",
  "line_items": [
    {
      "quantity": "1",
      "unit_price": "100.00",
      "billing_period_end": "2026-02-01T00:00:00Z",
      "billing_period_start": "2026-01-01T00:00:00Z",
      "description": "<string>",
      "product_id": "<string>"
    }
  ],
  "merchant_id": "mrch_01H8XGJWBWBAQ4PLwXYZ",
  "payment": {
    "source": "payment_card",
    "note": "<string>",
    "paid_at": "2023-11-07T05:31:56Z",
    "reference": "<string>"
  },
  "purchase_order_number": "<string>",
  "tax_calculation_id": "<string>"
}
'

import requests

url = "https://api.alguna.io/invoices"

payload = {
    "autopay_timing": "on_due_date",
    "billing_period_end": "2026-02-01T00:00:00Z",
    "billing_period_start": "2026-01-01T00:00:00Z",
    "currency": "USD",
    "customer_id": "<string>",
    "description": "<string>",
    "issue_date": "2023-11-07T05:31:56Z",
    "line_items": [
        {
            "quantity": "1",
            "unit_price": "100.00",
            "billing_period_end": "2026-02-01T00:00:00Z",
            "billing_period_start": "2026-01-01T00:00:00Z",
            "description": "<string>",
            "product_id": "<string>"
        }
    ],
    "merchant_id": "mrch_01H8XGJWBWBAQ4PLwXYZ",
    "payment": {
        "source": "payment_card",
        "note": "<string>",
        "paid_at": "2023-11-07T05:31:56Z",
        "reference": "<string>"
    },
    "purchase_order_number": "<string>",
    "tax_calculation_id": "<string>"
}
headers = {
    "Alguna-Version": "<alguna-version>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Alguna-Version': '<alguna-version>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    autopay_timing: 'on_due_date',
    billing_period_end: '2026-02-01T00:00:00Z',
    billing_period_start: '2026-01-01T00:00:00Z',
    currency: 'USD',
    customer_id: '<string>',
    description: '<string>',
    issue_date: '2023-11-07T05:31:56Z',
    line_items: [
      {
        quantity: '1',
        unit_price: '100.00',
        billing_period_end: '2026-02-01T00:00:00Z',
        billing_period_start: '2026-01-01T00:00:00Z',
        description: '<string>',
        product_id: '<string>'
      }
    ],
    merchant_id: 'mrch_01H8XGJWBWBAQ4PLwXYZ',
    payment: {
      source: 'payment_card',
      note: '<string>',
      paid_at: '2023-11-07T05:31:56Z',
      reference: '<string>'
    },
    purchase_order_number: '<string>',
    tax_calculation_id: '<string>'
  })
};

fetch('https://api.alguna.io/invoices', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "amount_paid": "0.00",
  "amount_remaining": "110.00",
  "billing_period": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "currency": "USD",
  "customer_id": "<string>",
  "description": "<string>",
  "id": "<string>",
  "line_items": [
    {
      "amount_excluding_tax": "73.98",
      "amount_including_tax": "80.55",
      "description": "<string>",
      "id": "<string>",
      "is_editable": true,
      "quantity": "1",
      "total_price": "100.00",
      "unit_price": "100.00",
      "billing_period_end": "2023-11-07T05:31:56Z",
      "billing_period_start": "2023-11-07T05:31:56Z",
      "product_id": "<string>",
      "tax_amount": "6.57",
      "tax_rate": "8.875"
    }
  ],
  "status": "draft",
  "subtotal": "100.00",
  "tax": "10.00",
  "total": "110.00",
  "updated_at": "2023-11-07T05:31:56Z",
  "autopay_timing": "on_due_date",
  "billing_period_end": "2023-11-07T05:31:56Z",
  "billing_period_start": "2023-11-07T05:31:56Z",
  "due_date": "2023-11-07T05:31:56Z",
  "external_id": "<string>",
  "external_provider": "<string>",
  "external_reference": "<string>",
  "external_url": "<string>",
  "invoicing_date": "2023-11-07T05:31:56Z",
  "issue_date": "2023-11-07T05:31:56Z",
  "merchant_id": "mrch_01H8XGJWBWBAQ4PLwXYZ",
  "paid_date": "2023-11-07T05:31:56Z",
  "purchase_order_number": "<string>",
  "tax_calculation_id": "<string>"
}

{
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

Authorizations

Authorization

string

header

required

API key authentication. Pass your API key as a Bearer token.

Headers

Alguna-Version

enum<string>

required

Available options:

2026-04-01

Idempotency-Key

string

A unique string that makes a retried write safe. If you send the same request with the same key within 24 hours, the API returns the stored response and does not run the request again. A 5xx or 429 response is not stored, so a retry with that key runs the request again.

Maximum string length: 255

Example:

"ik_a1b2c3d4e5f6"

Body

application/json

autopay_timing

enum<string> | null

When auto-pay charges the invoice. on_issue: when the invoice is issued. on_due_date: on the invoice's due date. Omit it to inherit the customer's Autopay Timing. Not allowed with tax_calculation_id.

Available options:

on_issue,

on_due_date

Example:

"on_due_date"

billing_period_end

string<date-time> | null

End of the invoice's billing period, exclusive: for a period through 31 January send 2026-02-01T00:00:00Z. Send with billing_period_start.

Example:

"2026-02-01T00:00:00Z"

billing_period_start

string<date-time> | null

Start of the invoice's billing period, inclusive. Send with billing_period_end.

Example:

"2026-01-01T00:00:00Z"

currency

string

ISO 4217 currency code; required unless tax_calculation_id is set

Example:

"USD"

customer_id

string

Existing customer to bill. On the tax_calculation_id path, leave empty to mint a guest customer from the calculation's buyer.

description

string | null

Invoice description or memo

issue_date

string<date-time> | null

Date to issue the invoice

line_items

object[]

Line items to include on the invoice

Show child attributes

merchant_id

string | null

Existing sub-merchant the invoice is issued for; you remain the seller of record. Create the merchant before referencing it here. Optional alongside tax_calculation_id, where it must match the merchant the calculation was made for. Requires the merchants entitlement

Example:

"mrch_01H8XGJWBWBAQ4PLwXYZ"

payment

object | null

Record the customer's already-settled payment and mark the invoice paid in the same call; requires tax_calculation_id

Show child attributes

purchase_order_number

string | null

Purchase order number

status

enum<string> | null

Initial invoice status. Defaults to draft. Setting issued releases the invoice for issuance, which completes asynchronously: the response returns the invoice in processing, and it settles to issued shortly after — poll the Get Invoice endpoint to observe the final status. paid is only valid on the tax_calculation_id path and must be sent together with a payment.

Available options:

draft,

issued,

paid

tax_calculation_id

string | null

Id of a persisted tax calculation; its stored line items, tax amounts, and buyer become the invoice, which is issued synchronously with no recalculation. Mutually exclusive with line_items (the calculation supplies them). Leave status unset or set it to issued to issue the invoice; set status to paid together with a payment to also mark it paid.

Response

Success

amount_paid

string

required

Amount that has been paid

Example:

"0.00"

amount_remaining

string

required

Remaining amount due

Example:

"110.00"

billing_period

string

required

Formatted billing period string

created_at

string<date-time>

required

Timestamp when the invoice was created

currency

string

required

ISO 4217 currency code

Example:

"USD"

customer_id

string

required

Customer this invoice belongs to

description

string

required

Invoice description or memo

string

required

Unique identifier for the invoice

line_items

object[]

required

Line items on this invoice

Show child attributes

status

enum<string>

required

Current status of the invoice

Available options:

draft,

upcoming,

pending_approval,

scheduled,

processing,

issued,

void,

paid,

canceled,

overdue

subtotal

string

required

Sum of all line item totals before tax

Example:

"100.00"

tax

string

required

Total tax amount

Example:

"10.00"

total

string

required

Total amount including tax

Example:

"110.00"

updated_at

string<date-time>

required

Timestamp when the invoice was last updated

autopay_timing

enum<string> | null

When auto-pay charges the invoice. Before issue, it is null when the invoice inherits the value of its subscription or customer. At issue, the resolved value is saved on the invoice. Invoices issued without a value are charged when they are issued.

Available options:

on_issue,

on_due_date

Example:

"on_due_date"

billing_period_end

string<date-time> | null

End of the billing period

billing_period_start

string<date-time> | null

Start of the billing period

due_date

string<date-time> | null

Date the invoice payment is due

external_id

string

Identifier in the external payment provider

external_provider

string

External payment provider name

external_reference

string

Customer-facing invoice reference number

external_url

string

URL to the invoice in the external system

invoicing_date

string<date-time> | null

Date the invoice is scheduled for processing

issue_date

string<date-time> | null

Date the invoice was issued

merchant_id

string | null

Sub-merchant the invoice was issued for; you remain the seller of record

Example:

"mrch_01H8XGJWBWBAQ4PLwXYZ"

paid_date

string<date-time> | null

Date the invoice was paid

purchase_order_number

string | null

Purchase order number

tax_calculation_id

string | null

Id of the tax calculation this invoice was created from, if any

⌘I

Create an invoice

curl --request POST \
  --url https://api.alguna.io/invoices \
  --header 'Alguna-Version: <alguna-version>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "autopay_timing": "on_due_date",
  "billing_period_end": "2026-02-01T00:00:00Z",
  "billing_period_start": "2026-01-01T00:00:00Z",
  "currency": "USD",
  "customer_id": "<string>",
  "description": "<string>",
  "issue_date": "2023-11-07T05:31:56Z",
  "line_items": [
    {
      "quantity": "1",
      "unit_price": "100.00",
      "billing_period_end": "2026-02-01T00:00:00Z",
      "billing_period_start": "2026-01-01T00:00:00Z",
      "description": "<string>",
      "product_id": "<string>"
    }
  ],
  "merchant_id": "mrch_01H8XGJWBWBAQ4PLwXYZ",
  "payment": {
    "source": "payment_card",
    "note": "<string>",
    "paid_at": "2023-11-07T05:31:56Z",
    "reference": "<string>"
  },
  "purchase_order_number": "<string>",
  "tax_calculation_id": "<string>"
}
'

import requests

url = "https://api.alguna.io/invoices"

payload = {
    "autopay_timing": "on_due_date",
    "billing_period_end": "2026-02-01T00:00:00Z",
    "billing_period_start": "2026-01-01T00:00:00Z",
    "currency": "USD",
    "customer_id": "<string>",
    "description": "<string>",
    "issue_date": "2023-11-07T05:31:56Z",
    "line_items": [
        {
            "quantity": "1",
            "unit_price": "100.00",
            "billing_period_end": "2026-02-01T00:00:00Z",
            "billing_period_start": "2026-01-01T00:00:00Z",
            "description": "<string>",
            "product_id": "<string>"
        }
    ],
    "merchant_id": "mrch_01H8XGJWBWBAQ4PLwXYZ",
    "payment": {
        "source": "payment_card",
        "note": "<string>",
        "paid_at": "2023-11-07T05:31:56Z",
        "reference": "<string>"
    },
    "purchase_order_number": "<string>",
    "tax_calculation_id": "<string>"
}
headers = {
    "Alguna-Version": "<alguna-version>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Alguna-Version': '<alguna-version>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    autopay_timing: 'on_due_date',
    billing_period_end: '2026-02-01T00:00:00Z',
    billing_period_start: '2026-01-01T00:00:00Z',
    currency: 'USD',
    customer_id: '<string>',
    description: '<string>',
    issue_date: '2023-11-07T05:31:56Z',
    line_items: [
      {
        quantity: '1',
        unit_price: '100.00',
        billing_period_end: '2026-02-01T00:00:00Z',
        billing_period_start: '2026-01-01T00:00:00Z',
        description: '<string>',
        product_id: '<string>'
      }
    ],
    merchant_id: 'mrch_01H8XGJWBWBAQ4PLwXYZ',
    payment: {
      source: 'payment_card',
      note: '<string>',
      paid_at: '2023-11-07T05:31:56Z',
      reference: '<string>'
    },
    purchase_order_number: '<string>',
    tax_calculation_id: '<string>'
  })
};

fetch('https://api.alguna.io/invoices', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "amount_paid": "0.00",
  "amount_remaining": "110.00",
  "billing_period": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "currency": "USD",
  "customer_id": "<string>",
  "description": "<string>",
  "id": "<string>",
  "line_items": [
    {
      "amount_excluding_tax": "73.98",
      "amount_including_tax": "80.55",
      "description": "<string>",
      "id": "<string>",
      "is_editable": true,
      "quantity": "1",
      "total_price": "100.00",
      "unit_price": "100.00",
      "billing_period_end": "2023-11-07T05:31:56Z",
      "billing_period_start": "2023-11-07T05:31:56Z",
      "product_id": "<string>",
      "tax_amount": "6.57",
      "tax_rate": "8.875"
    }
  ],
  "status": "draft",
  "subtotal": "100.00",
  "tax": "10.00",
  "total": "110.00",
  "updated_at": "2023-11-07T05:31:56Z",
  "autopay_timing": "on_due_date",
  "billing_period_end": "2023-11-07T05:31:56Z",
  "billing_period_start": "2023-11-07T05:31:56Z",
  "due_date": "2023-11-07T05:31:56Z",
  "external_id": "<string>",
  "external_provider": "<string>",
  "external_reference": "<string>",
  "external_url": "<string>",
  "invoicing_date": "2023-11-07T05:31:56Z",
  "issue_date": "2023-11-07T05:31:56Z",
  "merchant_id": "mrch_01H8XGJWBWBAQ4PLwXYZ",
  "paid_date": "2023-11-07T05:31:56Z",
  "purchase_order_number": "<string>",
  "tax_calculation_id": "<string>"
}

{
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

API Reference

Examples

SDKs

API Reference

Webhooks

Create an invoice

Authorizations

Headers

Body

Response