Billing API¶

Inspect your subscription and the plans available to you, and (when Stripe is configured) start a Stripe Checkout or Customer Portal session.

Subscription and plan data are read from InvoicePDFs' own database, so those endpoints always work. The checkout and portal endpoints require Stripe to be configured on the server; when it is not, they return 501 Not Implemented with error code not_configured.

Get Subscription¶

GET /api/v1/billing/subscription

Returns the current subscription status straight from the database — no Stripe API call is made, so this works whether or not Stripe is configured.

Response:

{
  "data": {
    "subscription_id": "sub_123",
    "status": "active",
    "plan_id": "plan_free",
    "plan_name": "Free",
    "stripe_configured": false,
    "has_billing_account": false
  }
}

Field	Description
`subscription_id`	Stripe subscription ID, or `null` if none
`status`	Subscription status, or `null` if none
`plan_id`	ID of the account's current plan
`plan_name`	Display name of the current plan
`stripe_configured`	Whether Stripe billing is configured on the server
`has_billing_account`	Whether a Stripe customer exists for this account

Try it

List Plans¶

GET /api/v1/billing/plans

Lists purchasable plans — those wired to a Stripe price. Read from the database.

Response:

{
  "data": [
    {
      "id": "plan_pro",
      "name": "Pro",
      "price_id": "price_123",
      "monthly_render_quota": 1000
    }
  ]
}

Field	Description
`id`	Plan ID
`name`	Plan display name
`price_id`	Stripe price ID used when starting checkout
`monthly_render_quota`	Number of PDF renders included per month

Try it

Create Checkout Session¶

POST /api/v1/billing/checkout-session

Creates a Stripe Checkout session for a subscription. A Stripe customer is lazily created for the account if one does not already exist.

Request:

{
  "price_id": "price_123"
}

Field	Required	Description
`price_id`	Yes	Stripe price ID for the plan to subscribe to

Response:

{
  "data": {
    "session_id": "cs_test_123",
    "url": "https://checkout.stripe.com/c/pay/cs_test_123"
  }
}

Redirect the user to url to complete payment.

Note

Requires Stripe to be configured on the server. If it is not, this endpoint returns 501 Not Implemented with error code not_configured.

Try it

Create Portal Session¶

POST /api/v1/billing/portal-session

Creates a Stripe Customer Portal session for self-service subscription management (updating payment methods, canceling, viewing invoices).

Response:

{
  "data": {
    "url": "https://billing.stripe.com/p/session/123"
  }
}

Redirect the user to url to manage their subscription.

Note

Requires Stripe to be configured on the server; otherwise this endpoint returns 501 Not Implemented with error code not_configured. If no billing account exists for the account yet, it returns 400 Bad Request with error code bad_request — subscribe first.

Try it

Update Overage Settings¶

PATCH /api/v1/billing/overage

Try it