baynoy

API reference

Invoices

Invoices flow from draft → open → paid. POST creates a draft. The send endpoint emails the customer (and a copy to the merchant team + ops) with a PDF and hosted-checkout link, and flips the status from draft to open. Marking paid manually is for off-platform payments (bank transfer the merchant received separately).

Create an invoice

POST/v1/invoicesscope: invoices:write

Lands as a draft. Use the dashboard or the send endpoint to email it. The invoice number auto-generates as an 8-digit number when omitted; supply your own for ERP integration parity (must be unique per merchant).

Body parameters

customerId

string

Attach a Customer. Optional but strongly recommended — without it the email gate falls back to billing_details on the eventual payment.
currencyrequired

string

ISO 4217 code.
itemsrequired

array

Line items. Each `{description, qty, unitAmount, taxRate?}`. unitAmount in minor units; taxRate in 0–100 percent.
number

string

Custom invoice number. Auto-generated when omitted.
dueAt

string

ISO 8601 datetime. Defaults to 14 days from creation.
issuedAt

string

ISO 8601 datetime. Defaults to now.
notes

string

Free-form footer text. Shown on PDF + email.
curl https://baynoy.com/api/v1/invoices \
  -H "Authorization: Bearer sk_live_…" \
  -H "Idempotency-Key: inv-2026-05-27-001" \
  -d '{
    "customerId": "8f7e6d5c-...",
    "currency": "CHF",
    "items": [
      {"description": "Consulting fee", "qty": 1, "unitAmount": 50000},
      {"description": "VAT", "qty": 1, "unitAmount": 4000, "taxRate": 8}
    ],
    "dueAt": "2026-06-10T00:00:00Z"
  }'
Response
{
  "ok": true,
  "data": {
    "id": "inv_5d4c3b-...",
    "number": "23133961",
    "status": "draft",
    "currency": "CHF",
    "subtotal": "50000",
    "taxTotal": "4000",
    "total": "54000",
    "items": [...],
    "customer": { "id": "...", "name": "Acme", "email": "[email protected]" },
    "issuedAt": "2026-05-27T12:34:56.789Z",
    "dueAt": "2026-06-10T00:00:00.000Z",
    "paidAt": null,
    "createdAt": "2026-05-27T12:34:56.789Z"
  }
}

Send an invoice

POST/v1/invoices/{id}/sendscope: invoices:write

Emails the customer the invoice as a PDF with a hosted-checkout link, copies the merchant team and ops mailbox, and flips the status from draft → open. Idempotent — re-sending an already-open invoice is a no-op except for re-delivering the email.

Path parameters

idrequired

string

Invoice UUID.
curl -X POST https://baynoy.com/api/v1/invoices/inv_5d4c3b-.../send \
  -H "Authorization: Bearer sk_live_…"
Response
{
  "ok": true,
  "data": {
    "sent": true,
    "to": "[email protected]",
    "merchantCopies": 2,
    "payUrl": "https://baynoy.com/pay/inv/inv_5d4c3b-..."
  }
}