Skip to main content
Formal billing documents with auto-generated invoice numbers, due dates, and line items. Publish before collecting payment. Try in API Reference: Create · List · Publish · Receipt

​
When to use

  • B2B billing, consulting, subscriptions with explicit line items
  • Hosted payment links (as_payment_link: true) — see Hosted checkout

​
Lifecycle

StatusMeaning
IDLEDraft — editable
ACTIVEPublished — ready to pay
PROCESSINGPayment in flight
PAIDSettled
CANCELEDNo longer payable

​
Typical flow

  1. POST /v1/invoices/create (requires counterparty_id)
  2. POST /v1/invoices/{invoice_id}/items/add for each line
  3. PUT /v1/invoices/publish/{id} → ACTIVE
  4. Collect via hosted checkout or API-embedded session → execution → status

​
Create

curl -X POST "https://api.heydollr.app/v1/invoices/create" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "counterparty_id": 15,
    "currency": "USD",
    "note": "Consulting services",
    "fee_bearer": "PAYER",
    "as_payment_link": true,
    "due_date": "2025-12-31T23:59:59Z"
  }'

​
List

curl "https://api.heydollr.app/v1/invoices/list?currency=USD&status=ACTIVE" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Optional filters: currency (ISO 4217), status.

​
Retrieve

By system ID: 
curl "https://api.heydollr.app/v1/invoices/retrieve/101" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
By invoice number: 
curl "https://api.heydollr.app/v1/invoices/retrieve/number/INV-2025-0042" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Detail responses include invoice_items and embedded counterparty.

​
Update (draft only)

curl -X PUT "https://api.heydollr.app/v1/invoices/update/101" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"note": "Updated scope", "fee_bearer": "PAYEE"}'
Only IDLE invoices can be edited.

​
Line items

Add: 
curl -X POST "https://api.heydollr.app/v1/invoices/101/items/add" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Strategy Session", "currency": "USD", "qty": 1, "amount": 250.00}'
Update: 
curl -X PUT "https://api.heydollr.app/v1/invoices/101/items/7/update" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"qty": 2, "amount": 200.00}'
Remove: 
curl -X DELETE "https://api.heydollr.app/v1/invoices/101/items/7/remove" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Publish & cancel

curl -X PUT "https://api.heydollr.app/v1/invoices/publish/101" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

curl -X DELETE "https://api.heydollr.app/v1/invoices/cancel/101" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Receipt

curl "https://api.heydollr.app/v1/invoices/receipt/101" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

curl "https://api.heydollr.app/v1/invoices/receipt/number/INV-2025-0042" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Available once status is PAID. Includes fee breakdown, FX, provider, and line items.

​
State transitions

FromActionToNotes
—CreateIDLEDraft, editable
IDLEAdd/update/remove itemsIDLE
IDLEPublishACTIVELocked for editing
ACTIVECustomer paysPROCESSINGPayment in flight
PROCESSINGSettlesPAIDFinal
IDLE or ACTIVECancelCANCELEDNot payable
PROCESSING——Do not cancel; wait for payment result
Cannot edit line items after publish. Cannot cancel while PROCESSING.
Last modified on June 23, 2026