REST API endpoints for invoices

Create, list, retrieve, and void stablecoin invoices. Each invoice maps to an on-chain PDA and includes a hosted checkout URL for customer payment.

Invoices are the core payment primitive in Marlin. When you create an invoice, Marlin returns a hostedCheckoutUrl your customer visits to pay and an unsignedTx you sign and submit to register the invoice on-chain. Supported stablecoins are USDC, PYUSD, and USDG.

---

POST /api/invoices

Create a new invoice for a customer. The customer is identified by their Solana wallet address and is automatically upserted — you do not need to create a customer record separately.

Request body

customerWallet · string · required

The customer’s Solana wallet address (base58, 32–44 characters).

lineItems · object[] · required

At least one line item. Maximum 50 per invoice.

Show line item properties

description · string · required

Label for this line item (1–500 characters).

quantity · number · required

Integer quantity, minimum 1.

unitPrice · string · required

Decimal price string, e.g. "9.99". Up to 6 decimal places.

mint · string · required

Stablecoin to request payment in. One of USDC, PYUSD, or USDG.

taxBps · number · default: "0"

Tax in basis points applied to the subtotal (0–10000). 100 bps = 1%.

memo · string

Optional internal note attached to the invoice (max 500 characters).

dueDate · string

ISO 8601 datetime string for the payment due date, e.g. "2026-06-01T00:00:00Z".

customerEmail · string

Customer email address. Marlin sends an invoice notification email to this address when the invoice is created.

customerLabel · string

Display name for the customer (max 100 characters).

Response — 201 Created

invoice · object · required

The created invoice object.

Hide invoice fields

id · string

Database UUID for the invoice.

onchainId · string

Hex-encoded ULID that identifies the invoice on-chain.

merchantId · string

Your merchant account ID.

customerId · string

The upserted customer’s ID.

mint · string

Stablecoin mint: USDC, PYUSD, or USDG.

amount · string

Total invoice amount as a decimal string (subtotal + tax).

status · string

Initial status is Open.

memo · string | null

Invoice memo.

expiresAt · string | null

ISO 8601 due date, or null.

hostedCheckoutUrl · string

URL your customer visits to pay this invoice.

customer · object

Nested customer snapshot with walletAddress, label, and email.

createdAt · string

ISO 8601 creation timestamp.

updatedAt · string

ISO 8601 last-updated timestamp.

unsignedTx · string

Base64-encoded unsigned Solana transaction. Sign this with your merchant wallet and submit it to register the invoice on-chain.

hostedCheckoutUrl · string

Convenience duplicate of invoice.hostedCheckoutUrl.

curl

curl --request POST https://api.marlin.dev/api/invoices \
  --header "Authorization: Bearer sk_live_abc123" \
  --header "Content-Type: application/json" \
  --data '{
    "customerWallet": "7xKX...",
    "mint": "USDC",
    "lineItems": [
      {
        "description": "Pro plan — June 2026",
        "quantity": 1,
        "unitPrice": "49.00"
      }
    ],
    "taxBps": 0,
    "dueDate": "2026-06-15T00:00:00Z"
  }'

---

GET /api/invoices

List all invoices for your merchant account, ordered newest-first.

Query parameters

status · string

Filter by invoice status. One of Open, Paid, Cancelled, Expired.

search · string

Free-text search across onchainId, memo, customer label, and customer wallet address.

Response — 200 OK

Returns an array of invoice objects. Each object has the same shape as the invoice field in the create response, plus a nested customer object.

curl

curl https://api.marlin.dev/api/invoices?status=Open \
  --header "Authorization: Bearer sk_live_abc123"

---

GET /api/invoices/:id

Retrieve a single invoice by its database ID.

Path parameters

id · string · required

The invoice’s database UUID.

Response — 200 OK

Returns the invoice object, identical in shape to the create response, with an additional hostedCheckoutUrl field.

curl

curl https://api.marlin.dev/api/invoices/01HXYZ \
  --header "Authorization: Bearer sk_live_abc123"

---

POST /api/invoices/:id/void

Void an open invoice. You can only void invoices whose status is Open. Once voided, the invoice status changes to Cancelled and the customer can no longer pay it.

Path parameters

id · string · required

The invoice’s database UUID.

Response — 200 OK

Returns the updated invoice object with status: "Cancelled".

Error cases

• INVOICE_NOT_FOUND (404) — The invoice does not exist or does not belong to your account.
• INVOICE_NOT_OPEN (400) — The invoice is not in Open status and cannot be voided.

curl

curl --request POST \
  https://api.marlin.dev/api/invoices/01HXYZ/void \
  --header "Authorization: Bearer sk_live_abc123"