Create an invoice line item

POST

invoices

{id}

line-items

curl --request POST \
  --url https://api.alguna.io/invoices/{id}/line-items \
  --header 'Alguna-Version: <alguna-version>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "description": "<string>",
  "quantity": "1",
  "unit_price": "100.00",
  "billing_period_end": "2026-02-01T00:00:00Z",
  "billing_period_start": "2026-01-01T00:00:00Z"
}
'

import requests

url = "https://api.alguna.io/invoices/{id}/line-items"

payload = {
    "description": "<string>",
    "quantity": "1",
    "unit_price": "100.00",
    "billing_period_end": "2026-02-01T00:00:00Z",
    "billing_period_start": "2026-01-01T00:00:00Z"
}
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({
    description: '<string>',
    quantity: '1',
    unit_price: '100.00',
    billing_period_end: '2026-02-01T00:00:00Z',
    billing_period_start: '2026-01-01T00:00:00Z'
  })
};

fetch('https://api.alguna.io/invoices/{id}/line-items', 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"

Path Parameters

string

required

Unique identifier for the invoice

Body

application/json

description

string

required

Description of the line item

quantity

string

required

Quantity

Example:

"1"

unit_price

string

required

Unit price, excluding tax. Tax is calculated on top of it.

Example:

"100.00"

billing_period_end

string<date-time> | null

End of the service period this line covers, 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 service period this line covers, inclusive. Send with billing_period_end.

Example:

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

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 line item

curl --request POST \
  --url https://api.alguna.io/invoices/{id}/line-items \
  --header 'Alguna-Version: <alguna-version>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "description": "<string>",
  "quantity": "1",
  "unit_price": "100.00",
  "billing_period_end": "2026-02-01T00:00:00Z",
  "billing_period_start": "2026-01-01T00:00:00Z"
}
'

import requests

url = "https://api.alguna.io/invoices/{id}/line-items"

payload = {
    "description": "<string>",
    "quantity": "1",
    "unit_price": "100.00",
    "billing_period_end": "2026-02-01T00:00:00Z",
    "billing_period_start": "2026-01-01T00:00:00Z"
}
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({
    description: '<string>',
    quantity: '1',
    unit_price: '100.00',
    billing_period_end: '2026-02-01T00:00:00Z',
    billing_period_start: '2026-01-01T00:00:00Z'
  })
};

fetch('https://api.alguna.io/invoices/{id}/line-items', 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 line item

Authorizations

Headers

Path Parameters

Body

Response