invoice API

Invoice API

Create an invoice from line items or from one line of text. The response includes the customer link, the PDF link, tax and the amount due.

Base URL https://invoicetxt.com Auth Authorization: Bearer itxt_live_…

What this API does

The invoice API creates a real InvoiceTXT invoice on your account. You send the client, the due terms and the line items. The response gives you an id, a public link and a PDF link you can put in a text message.

Keys are created in the workspace under API. Send the key only from your server. A key shown in a browser app can be copied by anyone who can view the page.

An active paid plan is required. The monthly invoice limit is the same limit as the plan: 30 on Solo, 150 on Pro and 600 on Studio.

POST/v1/invoices

Create an invoice

POST https://invoicetxt.com/v1/invoices with a JSON body. Send items, or a text field such as "Oak Street Homes, 4 hrs deep clean @ 35, oven clean 45, due on receipt". If items is present, text is ignored, even when items is empty.

currency is a three-letter label, not a conversion. tax_rate is a percentage from 0 to 40. Amounts are calculated on the server. A created invoice starts as draft.

Field	Type		Description
`client`	string	required	Customer name. Maximum 160 characters. HTML tags are removed.
`due`	string	optional	Terms such as on receipt or net 14. Defaults to on receipt. Maximum 80 characters.
`currency`	string	optional	Three-letter label such as USD or EUR. This does not convert money. Anything else is stored as USD.
`tax_rate`	number	optional	Percentage from 0 to 40. Higher values are capped at 40. The server calculates the tax and the total.
`items`	array	optional	Line items, maximum 20. Each item uses description, quantity and rate. quantity must be greater than 0. If items is present, text is ignored.
`text`	string	optional	One line of up to 500 characters, such as "Oak Street Homes, 4 hrs deep clean @ 35, due on receipt". Use this or items.
`template`	string	optional	Optional template slug stored on the invoice. Maximum 80 characters.

cURL

curl https://invoicetxt.com/v1/invoices \
  -H 'Authorization: Bearer itxt_live_your_key' \
  -H 'Content-Type: application/json' \
  -d '{
  "client": "Oak Street Homes",
  "due": "on receipt",
  "currency": "USD",
  "tax_rate": 0,
  "items": [
    {"description": "Deep clean", "quantity": 4, "rate": 35},
    {"description": "Oven clean", "quantity": 1, "rate": 45}
  ]
}'

Example response

A successful create returns 201 and the invoice object. Put url in the text, SMS or WhatsApp message you send yourself. InvoiceTXT does not send that message. pdf_url is the file the customer can download from the link.

JSON

{
  "id": "a1b2c3d4e5",
  "number": "A1B2C3D4E5",
  "client": "Oak Street Homes",
  "due": "on receipt",
  "currency": "USD",
  "tax_rate": 0,
  "subtotal": 185,
  "tax": 0,
  "total": 185,
  "status": "draft",
  "items": [
    {"description": "Deep clean", "quantity": 4, "rate": 35, "amount": 140},
    {"description": "Oven clean", "quantity": 1, "rate": 45, "amount": 45}
  ],
  "url": "https://invoicetxt.com/i/a1b2c3d4e5",
  "pdf_url": "https://invoicetxt.com/download/a1b2c3d4e5.pdf",
  "viewed_at": null,
  "signed": null,
  "created_at": "2026-10-31 12:00:00"
}

GET/v1/invoices

List invoices

GET /v1/invoices returns the latest 50 invoices for the key’s account, newest first, inside a data array. Each entry uses the same invoice object as create.

cURL

curl https://invoicetxt.com/v1/invoices \
  -H 'Authorization: Bearer itxt_live_your_key'

GET/v1/invoices/{id}

Retrieve an invoice

GET /v1/invoices/{id} returns one invoice. The id is the 10-character token in the customer link, not a database number you choose.

Field	Type		Description
`id`	string	required	Path parameter. The 10-character id from the create response.

cURL

curl https://invoicetxt.com/v1/invoices/INVOICE_ID \
  -H 'Authorization: Bearer itxt_live_your_key'

Errors

Error bodies are JSON with an error string. Do not retry a 401 in a loop. Create a new key in the workspace and replace the old one. A 402 means the plan is inactive or the monthly invoice limit is used up.

Status	Meaning
`201`	The invoice was created. The body is the invoice object.
`401`	The API key is missing, unknown or revoked.
`402`	The workspace has no active paid plan, or this month’s invoice limit is already used.
`404`	That invoice id does not belong to this key.
`409`	This invoice already has an acknowledgement.
`422`	The body needs a client and at least one valid line, or the signer name is not usable.
`429`	This IP has sent more than 120 API requests in a minute.

JSON

{
  "error": "Add a client name."
}

Webhooks

Create the endpoint under API, then Webhooks. InvoiceTXT POSTs invoice.created, invoice.viewed, invoice.paid and invoice.signed. The JSON body has id, type, created_at and data. data is the invoice object. Verify X-InvoiceTXT-Signature, which is sha256= and the HMAC-SHA256 of the raw body using the endpoint secret.

Only public https URLs on port 443 are accepted. Private addresses are rejected so a webhook cannot be aimed at a machine inside your network by mistake.

JSON

{
  "id": "evt_8f3a1c0b9d2e4a17",
  "type": "invoice.paid",
  "created_at": "2026-10-31T12:00:00+00:00",
  "data": {
    "id": "a1b2c3d4e5",
    "client": "Oak Street Homes",
    "total": 185,
    "status": "paid",
    "url": "https://invoicetxt.com/i/a1b2c3d4e5"
  }
}