API Reference

Authentication

All API requests require a valid API key passed in the Authorization header. Keys are prefixed with gb_live_ (production) or gb_test_ (testing).

curl -H "Authorization: Bearer gb_live_a1b2c3d4e5f6..." \
  http://your-ghostbill.onion/v1/invoices

Base URL

All endpoints are relative to your GhostBill instance. The API is versioned under /v1/.

Tor:      http://your-ghostbill.onion/v1/
Clearnet: https://your-domain.com/v1/  (if configured)
Local:    http://127.0.0.1:8013/v1/

Invoices

Invoices are the core payment primitive. Each invoice generates a unique Monero subaddress and tracks payment through 7 deterministic states.

POST /v1/invoices

Create a new invoice. Returns a unique subaddress for payment.

curl -X POST /v1/invoices \
  -H "Authorization: Bearer gb_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount_xmr": "0.5",
    "description": "Order #1234",
    "expiry_minutes": 60,
    "metadata": {"order_id": "1234"}
  }'

GET /v1/invoices

List invoices with cursor pagination. Filter by status, date range.

GET /v1/invoices/:id

Get full invoice details including payment history and metadata.

POST /v1/invoices/:id/cancel

Cancel a pending invoice. Only works for invoices in pending status.

Payments

Payments are detected automatically when funds arrive at an invoice's subaddress. Each payment tracks 3 states: detected (in mempool),confirmed (sufficient confirmations), and orphaned (removed from chain).

GET /v1/payments

List all payments with cursor pagination.

GET /v1/payments/:id

Get payment details including transaction hash, confirmations, and associated invoice.

Subscriptions

Full recurring billing engine. See the Subscriptions Guide for detailed documentation.

POST /v1/subscriptions

Create a subscription for a customer with billing interval and amount.

GET /v1/subscriptions

List subscriptions with cursor pagination.

GET /v1/subscriptions/:id

Get subscription details including current invoice and billing history.

GET /v1/subscriptions/:id/renewal-log

View the complete renewal history for a subscription.

PATCH /v1/subscriptions/:id

Update subscription amount, interval, or metadata.

POST /v1/subscriptions/:id/pause

Pause a subscription. Billing stops until resumed.

POST /v1/subscriptions/:id/resume

Resume a paused subscription. Next invoice generated immediately.

POST /v1/subscriptions/:id/cancel

Cancel a subscription. Access continues until end of current billing period.

POST /v1/subscriptions/:id/prepay

Create a pre-payment invoice for future billing periods.

Customers

Customer records associate an external identifier with their subscriptions and payment history.

POST /v1/customers

Create a new customer. Use external_id to link to your system.

GET /v1/customers

List customers with cursor pagination.

GET /v1/customers/:id

Get customer details.

PATCH /v1/customers/:id

Update customer metadata or external_id.

Webhooks

GhostBill fires 20 webhook events covering the complete invoice, payment, and subscription lifecycle. All webhooks are signed with HMAC-SHA256 and include up to 7 automatic retries with exponential backoff.

Events:

• payment.detected, payment.confirmed, payment.orphaned
• invoice.paid, invoice.expired, invoice.partially_paid, invoice.overpaid, invoice.late_paid
• subscription.created, subscription.renewed, subscription.past_due, subscription.cancelled, subscription.payment_confirmed
• subscription.updated, subscription.paused, subscription.resumed, subscription.expired
• subscription.trial_started, subscription.trial_ended, subscription.prepaid

GET /v1/webhooks

List webhook delivery history.

GET /v1/webhooks/:id

Get delivery details including response status and retry attempts.

POST /v1/webhooks/:id/retry

Manually retry a failed delivery.

GET /v1/webhooks/dead-letters

View the Dead Letter Queue — deliveries that exhausted all retry attempts.

POST /v1/webhooks/dead-letters/:id/retry

Retry a dead-lettered delivery.

Cursor Pagination

All list endpoints use cursor-based pagination for consistent results even when data changes.

# First page
curl /v1/invoices?limit=20

# Next page (use last item's ID as cursor)
curl /v1/invoices?limit=20&cursor=inv_a1b2c3...

# Response includes pagination metadata:
# {
#   "data": [...],
#   "has_more": true,
#   "next_cursor": "inv_x9y8z7..."
# }

Error Handling

The API returns standard HTTP status codes with JSON error bodies:

{
  "error": {
    "code": "invoice_not_found",
    "message": "Invoice inv_... does not exist",
    "status": 404
  }
}

Common status codes: 400 (validation error), 401 (unauthorized),404 (not found), 409 (conflict / invalid state transition),429 (rate limited), 500 (server error).

Related Pages

• Getting Started — deploy and configure GhostBill
• Recurring Billing — subscription and customer endpoints
• Pricing — API is free, dashboard licenses from $49/month
• GhostBill vs BTCPay Server — feature comparison