Create a new Lightning invoice
Creates a BOLT11 invoice settling to the project's settlement wallet (linked on the dashboard — default wallet when none is linked). projectId is optional for project-scoped API keys. Authenticate with a zap_live_/zap_test_ API key (invoices:write scope) or a dashboard JWT. Test keys create testMode invoices (webhook livemode: false). Supports fiat denominations via the currency field.
bearerX-API-Version?stringAPI version for header-based versioning
"1""1""2"application/json- body
amount*numberAmount — in satoshis when currency is "sat" (default), or in the fiat currency when currency is e.g. "USD"
1 <= valuecurrency?stringDenomination: "sat" (default) or a fiat currency code (USD, EUR, GBP, INR, BRL, JPY, CAD, AUD). Fiat amounts are converted to sats at the current rate, snapshotted at creation.
description*stringInvoice description
projectId?stringProject ID. Optional when the API key is project-scoped (project keys fill this in automatically). The invoice settles to the project's configured settlement wallet.
providerId?stringDeprecatedDEPRECATED — settlement is resolved from the project's settlement wallet (dashboard → project → Settlement Wallet). Kept for backward compatibility with legacy LNbits-provider integrations; ignored for new integrations.
expirySeconds?numberExpiry time in seconds (default: 3600 = 1 hour)
60 <= value <= 86400metadata?Additional metadata (JSON)
couponCode?stringCoupon code — the project discount is applied and snapshotted on the invoice (amountDueSats = amount - discountSats). The payer pays amountDueSats.
successUrl?stringMerchant success URL — hosted checkout redirects here on payment (paymentHash + preimage appended). Stripe-style success redirect.
cancelUrl?stringMerchant cancel/back URL shown on the hosted checkout
Invoice created successfully
curl -X POST 'http://localhost:3001/api/v1/invoices' \ -H 'Content-Type: application/json' \ -d '{ "amount": 5000, "description": "Order #1234"}'