Billing

The billing API lets you manage subscription plans, view invoices, track voucher usage, and handle payments. Payments are processed through Stripe. All endpoints require authentication and access to the specified client account.

Endpoints

Status & Usage

Get Billing Status

GET /api/v2/billing/status

Returns the current billing status for a client account, including plan limits and payment method availability.

Query Parameters

Response

{
  "has_payment_method": true,
  "status": "ACTIVE",
  "can_process": true,
  "vouchers_used": 45,
  "vouchers_included": 100,
  "over_limit": false
}

Status Values

Get Voucher Usage

GET /api/v2/billing/usage

Returns voucher usage counts over a time period, useful for charting and analytics.

Query Parameters

Response

{
  "from_date": "2026-04-01",
  "to_date": "2026-04-30",
  "total": 145,
  "vouchers_included": 200,
  "data": [
    {
      "period": "2026-04-01",
      "count": 5
    },
    {
      "period": "2026-04-02",
      "count": 3
    }
  ]
}

The vouchers_included field is null if the account has no active plan.

Error Responses

Plans & Orders

List Available Items

GET /api/v2/billing/items

Returns all available billing items (plans and add-ons) for a client account.

Query Parameters

Response

Returns an array of item objects, each including a billing_metadata field with plan/add-on details.

Get Current Orders

GET /api/v2/billing/orders

Returns the currently selected plans and add-ons for a client account.

Query Parameters

Response

Returns an array of item collection entry objects, each containing item details with billing_metadata.

Update Orders

PUT /api/v2/billing/orders

Sets the billing plan and add-ons for a client account. Replaces the current selection.

Query Parameters

Request Body

A single object or an array of objects:

Example Request

[
  { "item_id": 10, "quantity": 1 },
  { "item_id": 15, "quantity": 2 }
]

Response

Returns the updated item collection entries with status 201 Created.

Error Responses

Billing Documents

List Documents

GET /api/v2/billing/documents

Returns a paginated list of billing documents (invoices and credit notes).

Query Parameters

Response

{
  "data": [
    {
      "id": 42,
      "document_type": "ARInvoice",
      "document_number": "SB-2026-0042",
      "document_date": "2026-04-01",
      "due_date": "2026-04-15",
      "document_status": "COMPLETED",
      "payment_status": "OPEN",
      "gross_total": 1250.00,
      "open_amount": 1250.00,
      "currency_code": "NOK",
      "pdf_url": "https://..."
    }
  ],
  "meta": {
    "page": 1,
    "pages": 3,
    "per_page": 50,
    "records": 125
  }
}

The pdf_url field is null if no PDF is available for the document.

Get Document

GET /api/v2/billing/documents/{id}

Returns a single billing document.

Query Parameters

Response

Returns a single document object (same shape as the list response items).

Error Responses

Download Document PDF

GET /api/v2/billing/documents/{id}/pdf

Redirects to a presigned URL for downloading the document PDF.

Query Parameters

Response

Returns a 302 Found redirect to the presigned S3 download URL.

Error Responses

Pay a Document

POST /api/v2/billing/documents/{id}/pay

Initiates payment for a single billing document. If a saved payment method exists, the charge is processed directly. Otherwise, a Stripe checkout URL is returned for redirect.

Query Parameters

Request Body

Example Request

{
  "success_url": "https://app.snapbooks.no/billing/success",
  "cancel_url": "https://app.snapbooks.no/billing"
}

Response (Direct Charge)

{
  "status": "processing",
  "payment_request_id": 123,
  "amount": 1250.00,
  "currency": "NOK"
}

Response (Redirect Required)

{
  "status": "pending_redirect",
  "payment_request_id": 123,
  "amount": 1250.00,
  "currency": "NOK",
  "checkout_url": "https://checkout.stripe.com/..."
}

Pay Multiple Documents

POST /api/v2/billing/pay

Creates a checkout session for paying one or more billing documents in a single transaction.

Query Parameters

Request Body

Example Request

{
  "document_ids": [42, 43],
  "success_url": "https://app.snapbooks.no/billing/success",
  "cancel_url": "https://app.snapbooks.no/billing"
}

Response

{
  "checkout_url": "https://checkout.stripe.com/...",
  "total_amount": 2500.00,
  "payment_request_id": 789
}

Error Responses

Payment Methods

List Payment Methods

GET /api/v2/billing/payment-methods

Returns saved payment methods (cards) for a client account.

Query Parameters

Response

[
  {
    "id": "pm_1234567890",
    "brand": "visa",
    "last4": "4242",
    "exp_month": 12,
    "exp_year": 2025,
    "is_default": true
  }
]

Returns an empty array if no payment methods are saved.

Add Payment Method

POST /api/v2/billing/payment-methods/setup

Creates a Stripe checkout session for securely adding a new payment method.

Query Parameters

Request Body

Response

{
  "checkout_url": "https://checkout.stripe.com/..."
}

Redirect the user to checkout_url to complete the card setup.

Error Responses

Set Default Payment Method

POST /api/v2/billing/payment-methods/{payment_method_id}/default

Sets a payment method as the default for the client account.

Query Parameters

Response

{
  "status": "ok"
}

Error Responses

Remove Payment Method

DELETE /api/v2/billing/payment-methods/{payment_method_id}

Removes a saved payment method from the client account.

Query Parameters

Response

{
  "status": "ok"
}

Error Responses

Attributes

Billing Document

Payment Method

Related Resources

• Client Accounts — the accounts that billing applies to