Create an invoice

curl -X POST https://api.satlane.com/v1/invoices \
  -H "Authorization: Bearer sl_test_XXX" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-123-attempt-1" \
  -d '{
    "amount": 49.99,
    "currency": "USD",
    "order_ref": "ORD-12345",
    "callback_url": "https://yourshop.com/webhooks/satlane",
    "success_url": "https://yourshop.com/orders/ORD-12345/thanks",
    "buyer_email": "buyer@example.com",
    "expires_in_minutes": 15,
    "metadata": { "cart_id": "abc123" }
  }'

Request fields

Field	Type	Required	Notes
`amount`	number	one of	Fiat amount. We lock a BTC/USD rate and convert to sats.
`currency`	string	one of	Must be `"USD"` at MVP.
`amount_sats`	string	one of	Skip fiat conversion, charge exact sats.
`order_ref`	string	optional	Your internal order ID. We don't constrain format.
`callback_url`	string	optional	Per-invoice webhook URL (overrides store-level endpoints).
`success_url`	string	optional	Hosted checkout redirects here after payment.
`buyer_email`	string	optional	If set, we can email the buyer a receipt later (Phase 9).
`expires_in_minutes`	int	optional	5–120, default from store settings.
`metadata`	object	optional	Free-form `string → string` map echoed on every webhook.

Response

{
  "invoice": {
    "id": "22872e14-4216-4c78-8fe1-088ea649f3c2",
    "status": "pending",
    "environment": "test",
    "address": "tb1q…",
    "amount_sats": "150234",
    "amount_btc": "0.00150234",
    "amount_fiat": 49.99,
    "fiat_currency": "USD",
    "btc_usd_rate": 33280.45,
    "amount_tolerance_sats": "375",
    "amount_paid_sats": "0",
    "expires_at": "2026-05-16T11:30:00.000Z",
    "late_payment_grace_minutes": 60,
    "late_payment_deadline_at": "2026-05-16T12:30:00.000Z",
    "conf_threshold": 1,
    "fee_sats": "1502",
    "payment_uri": "bitcoin:tb1q…?amount=0.00150234&label=…",
    "hosted_checkout_url": "https://pay.satlane.com/i/22872e14-…",
    "order_ref": "ORD-12345",
    "created_at": "2026-05-16T11:15:00.000Z",
    "...": "..."
  }
}

Response fields worth understanding

Field	What it means
`amount_sats`	The invoice amount, in satoshis. Vendor-facing source of truth.
`amount_paid_sats`	Running total of sats received on-chain so far (non-reverted). Lets you compute `remaining = amount_sats - amount_paid_sats` without an aggregate query.
`amount_tolerance_sats`	Per-invoice slack on the expected amount. Payments within `[amount_sats − tolerance, amount_sats + tolerance]` count as exact. Defaults are computed from the platform-wide setting `payment_tolerance_bp` (basis points, default 25 bp = 0.25%) clamped to `[10, 1000]` sats. This absorbs wallet fee estimation drift and BTC/fiat rate movement between invoice creation and broadcast. Set the platform setting to `0` to require strict matches.
`btc_usd_rate`	The BTC/USD rate we locked at creation. Network price moves after this point don't change what the buyer owes.
`late_payment_deadline_at`	ISO timestamp past which payments are no longer auto-credited. We keep watching the address until then.
`conf_threshold`	Confirmations required before status flips to `paid`. Defaults: 1 below $100 invoice value, 2 at $100+.
`fee_sats`	Platform fee accrued against your vendor account on this invoice's successful payment. Already factored into your dashboard's "unbilled" total.