Invoices API

The Invoices API gives your backend the same invoice capabilities the dashboard has, over the REST API — exactly like Stripe’s /v1/invoices surface.

Auth

Invoice endpoints accept secret (sk_…) or restricted (rk_…) keys only. Publishable (pk_…) keys are always rejected because invoices contain customer PII, amounts, and payment proofs — they are never client-safe. Dashboard sessions continue to work with the existing role-based access (invoices:read, invoices:write, invoices:send).

Publishable keys cannot read or write invoices. Use a server-side secret/restricted key from your backend.

Required key permissions

Operation	API-key permission (any one is enough)	Dashboard role
List / retrieve / download / export	`invoices.read` · `invoices.write` · `invoices.send` · `payments.write`	`invoices:read`
Create / mark paid/void / refund / credit note	`invoices.write` · `payments.write`	`invoices:write`
Resend by email	`invoices.send` · `invoices.write` · `payments.write`	`invoices:send`

A secret key with no explicit permission list is full-access (Stripe “standard secret”). A restricted key must carry an explicit invoice permission.

List invoices

GET /api/v1/invoices?status=ISSUED&q=acme
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Query params

string

Filter by status: DRAFT, ISSUED, PAID, VOID, or OVERDUE.

string

Search by invoice number, customer email, or customer wallet.

Response

{
  "invoices": [
    {
      "id": "in_abc123",
      "number": "INV-ACME-0001",
      "status": "ISSUED",
      "currency": "USDC",
      "customerEmail": "[email protected]",
      "customerWallet": "0xabc...",
      "subtotal": "100.000000",
      "taxTotal": "5.000000",
      "total": "105.000000",
      "amountPaid": "0.000000",
      "amountOutstanding": "105.000000",
      "issuedAt": "2026-09-20T12:00:00.000Z",
      "lineItems": [],
      "deliveries": [],
      "payments": [],
      "company": { "name": "Acme", "email": "[email protected]", "walletAddress": "0xabc..." },
      "paymentLinks": []
    }
  ]
}

Retrieve an invoice

GET /api/v1/invoices/:id
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Returns the full invoice with lineItems, deliveries, creditNotes, and refunds, plus a signed downloadUrl for the PDF and an iso20022DownloadUrl.

Download the invoice PDF

GET /api/v1/invoices/:id/download
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx

{
  "ok": true,
  "downloadUrl": "https://api.arcenpay.com/api/v1/invoices/in_abc123/public/download?kind=invoice&exp=...&sig=..."
}

The returned URL is HMAC-signed and expires (default 24h).

ISO 20022 export

GET /api/v1/invoices/:id/iso20022
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Returns a rem.001.001.07 ISO 20022 XML credit-transfer file for the invoice.

Create an invoice

POST /api/v1/invoices
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "currency": "USDC",
  "customerEmail": "[email protected]",
  "customerWallet": "0xabc...",
  "customerName": "Jane Doe",
  "planId": "pl_abc123",
  "dueAt": "2026-10-20T12:00:00.000Z",
  "lines": [
    { "description": "Pro plan — September", "quantity": 1, "unitAmount": 100, "taxRate": 5 }
  ]
}

The invoice is issued immediately, the PDF is rendered, and a invoice.issued webhook fires. When a customerEmail is provided, the invoice is emailed to the customer.

Update invoice status (mark paid / void / overdue)

PATCH /api/v1/invoices/:id
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "status": "PAID",
  "paymentProof": { "txHash": "0x...", "payerWallet": "0x..." }
}

Allowed transitions: Marking an invoice paid records the Payment, fires the invoice.paid webhook, and sends the customer a receipt.

Credit notes

# List credit notes
GET /api/v1/invoices/:id/credit-notes
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx

# Create a credit note
POST /api/v1/invoices/:id/credit-notes
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{ "reason": "Customer requested partial refund", "amount": 25 }

Credit notes reduce the creditable balance, post a company credit (for paid invoices), and email the customer.

Refunds

# List refunds
GET /api/v1/invoices/:id/refunds
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx

# Create a refund (paid invoices only)
POST /api/v1/invoices/:id/refunds
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "amount": 25,
  "reason": "Customer requested refund",
  "refundProof": { "txHash": "0x...", "recipientWallet": "0x..." }
}

The refund proof is verified on-chain before the refund is recorded.

Resend by email

POST /api/v1/invoices/:id/resend
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Rate-limited via Arcjet (reset bursts are throttled). Requires the invoice to have a customerEmail.

Errors

Status	Meaning
`401`	Missing/invalid/revoked API key
`403`	Publishable key used, or the key lacks the required invoice permission
`404`	Invoice not found in this team/environment
`409`	Invalid status transition, or the invoice cannot be refunded/credited in its current state
`422`	Credit amount exceeds the remaining creditable balance
`429`	Resend rate limit exceeded

API-key calls are scoped to the team and the workspace environment the key was created in. A sk_test_… key only sees the development invoices; a sk_live_… key only sees production invoices.

Get started

Credentials

Companies

Users

Events

Access control

Features

Subscriptions

Checkout sessions

Payment links

Invoices

Autonomous agents

Escrow

Mandates

Coupons

zkTLS proofs

Public specs

Auth

Required key permissions

List invoices

Query params

Response

Retrieve an invoice

Download the invoice PDF

ISO 20022 export

Create an invoice

Update invoice status (mark paid / void / overdue)

Credit notes

Refunds

Resend by email

Errors

​Auth

​Required key permissions

​List invoices

​Query params

​Response

​Retrieve an invoice

​Download the invoice PDF

​ISO 20022 export

​Create an invoice

​Update invoice status (mark paid / void / overdue)

​Credit notes

​Refunds

​Resend by email

​Errors

Auth

Required key permissions

List invoices

Query params

Response

Retrieve an invoice

Download the invoice PDF

ISO 20022 export

Create an invoice

Update invoice status (mark paid / void / overdue)

Credit notes

Refunds

Resend by email

Errors