API reference

The Waffo Usage Billing API manages customers, contracts, seats, balances, and invoices, and decides whether each model call may run. This page is generated from the contract, so the fields and errors below match it.

Base URL

https://api.example.invalid

Authentication

Send Authorization: Bearer sk_test_xxx. Tenant secret key, or a portal token from POST /v1/portal_sessions. The tenant comes from the credential.

Key scopes nest: admin includes read, and read includes ingest. A portal token is bound to one customer and can call only the endpoints marked as allowed. Anywhere else it gets 403 insufficient_scope, and another customer's resource is 404 portal_scope_violation.

Idempotency

Every POST, PATCH, and DELETE needs an Idempotency-Key header. Unique per logical operation. Lives 48 hours. The same key with a different body is 409 idempotency_conflict. Replaying a key with the same body returns the stored response.

POST /v1/authorize: request_id in the body, keyed on (tenant, customer_id, request_id). No Idempotency-Key header.
POST /v1/ingest: transaction_id per event, deduped on (tenant, transaction_id) for 34 days. No Idempotency-Key header.

Response envelope

Success is {data, meta}, and lists add meta.next_page. Every success is HTTP 200, including creates and idempotent replays. Optional fields are omitted when unset. The invoice PDF is the one response without an envelope.

Errors are {error} with a code, message, retryable flag, request id, and the offending field when one applies.

Money

No JSON number carries money. Usage and credit amounts are decimal strings with at most 9 places, paired with credit_type_id. USD amounts are integer *_cents fields. A float in a money field, including 1999.0, is 400 validation_failed.

Enums

All enums are extensible. Clients must tolerate unknown values.

Success

{
  "data": {},
  "meta": {
    "request_id": "req_0001"
  }
}

List

{
  "data": [],
  "meta": {
    "request_id": "req_0001",
    "next_page": "page_0002"
  }
}

Error

{
  "error": {
    "code": "validation_failed",
    "message": "A required field is missing.",
    "retryable": false,
    "param": "amount",
    "request_id": "req_0001"
  }
}

Customers

List customers

GET/v1/customers

Scope: read
Portal tokens: Not allowed
Returns: A page of customers.

Parameters
Name	Type	Description
`limit`	integerin query	Page size. Default `25`Minimum `1`Maximum `100`
`next_page`	stringin query	Opaque cursor from `meta.next_page`.
`external_id`	stringin query	Filter by exact `external_id`.
`status`	enumin query	Values: `activearchived`

Response fields 7

Request

curl https://api.example.invalid/v1/customers \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json"

Response 200

{
  "data": [
    {
      "customer_id": "cus_0001",
      "name": "Kestrel Labs",
      "external_id": "kestrel-labs",
      "status": "active",
      "created_at": "2026-11-01T00:00:00Z"
    }
  ],
  "meta": {
    "request_id": "req_0001",
    "next_page": "page_0002"
  }
}

Errors 5

Create a customer

POST/v1/customers

Scope: admin
Portal tokens: Not allowed
Returns: Customer created, or the stored response on a replay.

Parameters
Name	Type	Description
`Idempotency-Key`required	stringin header	Unique per logical operation. Lives 48 hours. The same key with a different body is 409 `idempotency_conflict`. Min length `1`Max length `255`

Request body 3

Response fields 7

Request

curl -X POST https://api.example.invalid/v1/customers \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: idem_0001" \
  -d '{
  "name": "Kestrel Labs",
  "external_id": "kestrel-labs"
}'

Response 200

{
  "data": {
    "customer_id": "cus_0001",
    "name": "Kestrel Labs",
    "external_id": "kestrel-labs",
    "status": "active",
    "created_at": "2026-11-01T00:00:00Z"
  },
  "meta": {
    "request_id": "req_0001"
  }
}

Errors 7

Get a customer

GET/v1/customers/{id}

Scope: read
Portal tokens: Not allowed
Returns: The customer.

Parameters
Name	Type	Description
`id`required	stringin path	Id of the resource named in the path.

Response fields 7

Request

curl https://api.example.invalid/v1/customers/cus_0001 \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json"

Response 200

{
  "data": {
    "customer_id": "cus_0001",
    "name": "Kestrel Labs",
    "external_id": "kestrel-labs",
    "status": "active",
    "created_at": "2026-11-01T00:00:00Z"
  },
  "meta": {
    "request_id": "req_0001"
  }
}

Errors 5

Archive a customer

POST/v1/customers/{id}/archive

Scope: admin
Portal tokens: Not allowed
Returns: The archived customer.

Parameters
Name	Type	Description
`id`required	stringin path	Id of the resource named in the path.
`Idempotency-Key`required	stringin header	Unique per logical operation. Lives 48 hours. The same key with a different body is 409 `idempotency_conflict`. Min length `1`Max length `255`

Response fields 7

Request

curl -X POST https://api.example.invalid/v1/customers/cus_0001/archive \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: idem_0001"

Response 200

{
  "data": {
    "customer_id": "cus_0001",
    "name": "Kestrel Labs",
    "external_id": "kestrel-labs",
    "status": "active",
    "created_at": "2026-11-01T00:00:00Z"
  },
  "meta": {
    "request_id": "req_0001"
  }
}

Errors 7

Get the aggregate state of a customer

GET/v1/customers/{id}/state

Scope: read
Portal tokens: Not allowed
Returns: Active contract, seats, balances, budgets, and whether the customer is blocked.

Parameters
Name	Type	Description
`id`required	stringin path	Id of the resource named in the path.

Response fields 8

Request

curl https://api.example.invalid/v1/customers/cus_0001/state \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json"

Response 200

{
  "data": {
    "customer": {
      "customer_id": "cus_0001",
      "name": "Kestrel Labs",
      "external_id": "kestrel-labs",
      "status": "active",
      "created_at": "2026-11-01T00:00:00Z"
    },
    "seats": [
      {
        "seat_id": "seat_0001",
        "contract_id": "ctr_0001",
        "subscription_id": "sub_0001",
        "seat_tier": "standard",
        "status": "active",
        "starting_at": "2026-11-01T00:00:00Z"
      }
    ],
    "funds": {
      "credit_type_id": "ct_0001",
      "posted": "500",
      "reserved": "20",
      "available": "480",
      "customer_id": "cus_0001",
      "pool": {
        "credit_type_id": "ct_0001",
        "posted": "500",
        "reserved": "20",
        "available": "480"
      }
    },
    "budgets": [
      {
        "scope": "customer",
        "amount": "1000",
        "credit_type_id": "ct_0001",
        "period": "MONTH",
        "mode": "hard",
        "budget_id": "bgt_0001",
        "spent": "120",
        "status": "within_limit"
      }
    ],
    "blocked": false
  },
  "meta": {
    "request_id": "req_0001"
  }
}

Errors 5

Products

List products

GET/v1/products

Scope: read
Portal tokens: Not allowed
Returns: A page of products.

Parameters
Name	Type	Description
`limit`	integerin query	Page size. Default `25`Minimum `1`Maximum `100`
`next_page`	stringin query	Opaque cursor from `meta.next_page`.

Response fields 6

Request

curl https://api.example.invalid/v1/products \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json"

Response 200

{
  "data": [
    {
      "product_id": "prod_video_generate",
      "name": "video.generate",
      "event_type": "video_generate",
      "created_at": "2026-11-01T00:00:00Z"
    }
  ],
  "meta": {
    "request_id": "req_0001",
    "next_page": "page_0002"
  }
}

Errors 5

Create a product

POST/v1/products

Scope: admin
Portal tokens: Not allowed
Returns: Product created, or the stored response on a replay.

Parameters
Name	Type	Description
`Idempotency-Key`required	stringin header	Unique per logical operation. Lives 48 hours. The same key with a different body is 409 `idempotency_conflict`. Min length `1`Max length `255`

Request body 4

Response fields 6

Request

curl -X POST https://api.example.invalid/v1/products \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: idem_0001" \
  -d '{
  "name": "video.generate",
  "event_type": "video_generate"
}'

Response 200

{
  "data": {
    "product_id": "prod_video_generate",
    "name": "video.generate",
    "event_type": "video_generate",
    "created_at": "2026-11-01T00:00:00Z"
  },
  "meta": {
    "request_id": "req_0001"
  }
}

Errors 6

Credit types

Create a credit type

POST/v1/credit_types

Defines a custom pricing unit. The credit-to-USD rate lives on the contract, not here.

Scope: admin
Portal tokens: Not allowed
Returns: Credit type created, or the stored response on a replay.

Parameters
Name	Type	Description
`Idempotency-Key`required	stringin header	Unique per logical operation. Lives 48 hours. The same key with a different body is 409 `idempotency_conflict`. Min length `1`Max length `255`

Request body 2

Response fields 4

Request

curl -X POST https://api.example.invalid/v1/credit_types \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: idem_0001" \
  -d '{
  "name": "Credits",
  "unit_label": "credits"
}'

Response 200

{
  "data": {
    "credit_type_id": "ct_0001",
    "name": "Credits",
    "unit_label": "credits",
    "created_at": "2026-11-01T00:00:00Z"
  },
  "meta": {
    "request_id": "req_0001"
  }
}

Errors 6

Rate cards

Create a rate card

POST/v1/rate_cards

Scope: admin
Portal tokens: Not allowed
Returns: Rate card created, or the stored response on a replay.

Parameters
Name	Type	Description
`Idempotency-Key`required	stringin header	Unique per logical operation. Lives 48 hours. The same key with a different body is 409 `idempotency_conflict`. Min length `1`Max length `255`

Request body 2

Response fields 4

Request

curl -X POST https://api.example.invalid/v1/rate_cards \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: idem_0001" \
  -d '{
  "name": "Standard rates"
}'

Response 200

{
  "data": {
    "rate_card_id": "rc_0001",
    "name": "Standard rates",
    "created_at": "2026-11-01T00:00:00Z"
  },
  "meta": {
    "request_id": "req_0001"
  }
}

Errors 6

List the rates of a rate card

GET/v1/rate_cards/{id}/rates

Scope: read
Portal tokens: Not allowed
Returns: A page of rates.

Parameters
Name	Type	Description
`id`required	stringin path	Id of the resource named in the path.
`limit`	integerin query	Page size. Default `25`Minimum `1`Maximum `100`
`next_page`	stringin query	Opaque cursor from `meta.next_page`.
`product_id`	stringin query
`at`	timestampin query	Return rates in effect at this time.

Response fields 9

Request

curl https://api.example.invalid/v1/rate_cards/rc_0001/rates \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json"

Response 200

{
  "data": [
    {
      "rate_id": "rate_0001",
      "rate_card_id": "rc_0001",
      "product_id": "prod_video_generate",
      "rate_type": "PER_UNIT",
      "unit_price": "0.02",
      "credit_type_id": "ct_0001",
      "starting_at": "2026-11-01T00:00:00Z"
    }
  ],
  "meta": {
    "request_id": "req_0001",
    "next_page": "page_0002"
  }
}

Errors 6

Add a rate to a rate card

POST/v1/rate_cards/{id}/rates

Rates are versioned by their time window. A new rate never rewrites history.

Scope: admin
Portal tokens: Not allowed
Returns: Rate added, or the stored response on a replay.

Parameters
Name	Type	Description
`id`required	stringin path	Id of the resource named in the path.
`Idempotency-Key`required	stringin header	Unique per logical operation. Lives 48 hours. The same key with a different body is 409 `idempotency_conflict`. Min length `1`Max length `255`

Request body 7

Response fields 9

Request

curl -X POST https://api.example.invalid/v1/rate_cards/rc_0001/rates \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: idem_0001" \
  -d '{
  "product_id": "prod_video_generate",
  "rate_type": "PER_UNIT",
  "unit_price": "0.02",
  "credit_type_id": "ct_0001",
  "starting_at": "2026-11-01T00:00:00Z"
}'

Response 200

{
  "data": {
    "rate_id": "rate_0001",
    "rate_card_id": "rc_0001",
    "product_id": "prod_video_generate",
    "rate_type": "PER_UNIT",
    "unit_price": "0.02",
    "credit_type_id": "ct_0001",
    "starting_at": "2026-11-01T00:00:00Z"
  },
  "meta": {
    "request_id": "req_0001"
  }
}

Errors 9

Contracts

Create a contract

POST/v1/contracts

Scope: admin
Portal tokens: Not allowed
Returns: Contract created, or the stored response on a replay.

Parameters
Name	Type	Description
`Idempotency-Key`required	stringin header	Unique per logical operation. Lives 48 hours. The same key with a different body is 409 `idempotency_conflict`. Min length `1`Max length `255`

Request body 20

Response fields 24

Request

curl -X POST https://api.example.invalid/v1/contracts \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: idem_0001" \
  -d '{
  "customer_id": "cus_0001",
  "rate_card_id": "rc_0001",
  "starting_at": "2026-11-01T00:00:00Z",
  "credit_type_id": "ct_0001",
  "usd_cents_per_credit": "1",
  "recurring_credits": [
    {
      "allocation": "seat",
      "seat_tier": "standard",
      "amount": "1000",
      "credit_type_id": "ct_0001",
      "frequency": "MONTHLY"
    }
  ],
  "prepaid_balance_threshold_configuration": {
    "is_enabled": true,
    "threshold_amount": "100",
    "recharge_to_amount": "500",
    "credit_type_id": "ct_0001",
    "payment_gate_config": {
      "payment_gate_type": "EXTERNAL"
    }
  },
  "usage_statement_schedule": {
    "frequency": "MONTHLY"
  },
  "subscriptions": [
    {
      "seat_tier": "standard",
      "quantity": 10,
      "unit_price_cents": 3000,
      "billing_frequency": "MONTHLY"
    }
  ],
  "budgets": [
    {
      "scope": "customer",
      "amount": "1000",
      "credit_type_id": "ct_0001",
      "period": "MONTH",
      "mode": "hard"
    }
  ]
}'

Response 200

{
  "data": {
    "customer_id": "cus_0001",
    "rate_card_id": "rc_0001",
    "starting_at": "2026-11-01T00:00:00Z",
    "credit_type_id": "ct_0001",
    "usd_cents_per_credit": "1",
    "recurring_credits": [
      {
        "allocation": "seat",
        "seat_tier": "standard",
        "amount": "1000",
        "credit_type_id": "ct_0001",
        "frequency": "MONTHLY",
        "recurring_credit_id": "rcr_0001",
        "status": "active"
      }
    ],
    "prepaid_balance_threshold_configuration": {
      "is_enabled": true,
      "threshold_amount": "100",
      "recharge_to_amount": "500",
      "credit_type_id": "ct_0001",
      "payment_gate_config": {
        "payment_gate_type": "EXTERNAL"
      }
    },
    "usage_statement_schedule": {
      "frequency": "MONTHLY"
    },
    "contract_id": "ctr_0001",
    "status": "scheduled",
    "version": 1,
    "subscriptions": [
      {
        "seat_tier": "standard",
        "quantity": 10,
        "unit_price_cents": 3000,
        "billing_frequency": "MONTHLY",
        "subscription_id": "sub_0001",
        "unassigned_seats": 1
      }
    ],
    "budgets": [
      {
        "scope": "customer",
        "amount": "1000",
        "credit_type_id": "ct_0001",
        "period": "MONTH",
        "mode": "hard",
        "budget_id": "bgt_0001"
      }
    ],
    "created_at": "2026-11-01T00:00:00Z"
  },
  "meta": {
    "request_id": "req_0001"
  }
}

Errors 15

List the edit history of a contract

GET/v1/contracts/{id}/edits

Scope: read
Portal tokens: Not allowed
Returns: A page of contract edits, oldest first.

Parameters
Name	Type	Description
`id`required	stringin path	Id of the resource named in the path.
`limit`	integerin query	Page size. Default `25`Minimum `1`Maximum `100`
`next_page`	stringin query	Opaque cursor from `meta.next_page`.

Response fields 6

Request

curl https://api.example.invalid/v1/contracts/ctr_0001/edits \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json"

Response 200

{
  "data": [
    {
      "edit_id": "edit_0001",
      "contract_id": "ctr_0001",
      "version": 1,
      "starting_at": "2026-11-01T00:00:00Z",
      "created_at": "2026-11-01T00:00:00Z",
      "changes": {
        "starting_at": "2026-11-01T00:00:00Z",
        "add_budgets": [
          {
            "scope": "customer",
            "amount": "1000",
            "credit_type_id": "ct_0001",
            "period": "MONTH",
            "mode": "hard"
          }
        ]
      }
    }
  ],
  "meta": {
    "request_id": "req_0001",
    "next_page": "page_0002"
  }
}

Errors 6

Append an edit to a contract

POST/v1/contracts/{id}/edits

Edits append a new version and never rewrite historic prices. A portal token may send only the fields listed under Portal tokens.

Scope: admin
Portal tokens: Allowed. May write only: starting_atupdate_prepaid_balance_threshold_configurationadd_budgetsupdate_budgets
Returns: Edit recorded, or the stored response on a replay.

Parameters
Name	Type	Description
`id`required	stringin path	Id of the resource named in the path.
`Idempotency-Key`required	stringin header	Unique per logical operation. Lives 48 hours. The same key with a different body is 409 `idempotency_conflict`. Min length `1`Max length `255`

Request body 10

Response fields 6

Request

curl -X POST https://api.example.invalid/v1/contracts/ctr_0001/edits \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: idem_0001" \
  -d '{
  "starting_at": "2026-11-01T00:00:00Z",
  "add_budgets": [
    {
      "scope": "customer",
      "amount": "1000",
      "credit_type_id": "ct_0001",
      "period": "MONTH",
      "mode": "hard"
    }
  ]
}'

Response 200

{
  "data": {
    "edit_id": "edit_0001",
    "contract_id": "ctr_0001",
    "version": 1,
    "starting_at": "2026-11-01T00:00:00Z",
    "created_at": "2026-11-01T00:00:00Z",
    "changes": {
      "starting_at": "2026-11-01T00:00:00Z",
      "add_budgets": [
        {
          "scope": "customer",
          "amount": "1000",
          "credit_type_id": "ct_0001",
          "period": "MONTH",
          "mode": "hard"
        }
      ]
    }
  },
  "meta": {
    "request_id": "req_0001"
  }
}

Errors 20

Get a contract

GET/v1/contracts/{id}

Scope: read
Portal tokens: Not allowed
Returns: The contract at its latest version.

Parameters
Name	Type	Description
`id`required	stringin path	Id of the resource named in the path.

Response fields 24

Request

curl https://api.example.invalid/v1/contracts/ctr_0001 \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json"

Response 200

{
  "data": {
    "customer_id": "cus_0001",
    "rate_card_id": "rc_0001",
    "starting_at": "2026-11-01T00:00:00Z",
    "credit_type_id": "ct_0001",
    "usd_cents_per_credit": "1",
    "recurring_credits": [
      {
        "allocation": "seat",
        "seat_tier": "standard",
        "amount": "1000",
        "credit_type_id": "ct_0001",
        "frequency": "MONTHLY",
        "recurring_credit_id": "rcr_0001",
        "status": "active"
      }
    ],
    "prepaid_balance_threshold_configuration": {
      "is_enabled": true,
      "threshold_amount": "100",
      "recharge_to_amount": "500",
      "credit_type_id": "ct_0001",
      "payment_gate_config": {
        "payment_gate_type": "EXTERNAL"
      }
    },
    "usage_statement_schedule": {
      "frequency": "MONTHLY"
    },
    "contract_id": "ctr_0001",
    "status": "scheduled",
    "version": 1,
    "subscriptions": [
      {
        "seat_tier": "standard",
        "quantity": 10,
        "unit_price_cents": 3000,
        "billing_frequency": "MONTHLY",
        "subscription_id": "sub_0001",
        "unassigned_seats": 1
      }
    ],
    "budgets": [
      {
        "scope": "customer",
        "amount": "1000",
        "credit_type_id": "ct_0001",
        "period": "MONTH",
        "mode": "hard",
        "budget_id": "bgt_0001"
      }
    ],
    "created_at": "2026-11-01T00:00:00Z"
  },
  "meta": {
    "request_id": "req_0001"
  }
}

Errors 5

List the contracts of a customer

GET/v1/customers/{id}/contracts

Scope: read
Portal tokens: Not allowed
Returns: A page of contracts.

Parameters
Name	Type	Description
`id`required	stringin path	Id of the resource named in the path.
`limit`	integerin query	Page size. Default `25`Minimum `1`Maximum `100`
`next_page`	stringin query	Opaque cursor from `meta.next_page`.

Response fields 24

Request

curl https://api.example.invalid/v1/customers/cus_0001/contracts \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json"

Response 200

{
  "data": [
    {
      "customer_id": "cus_0001",
      "rate_card_id": "rc_0001",
      "starting_at": "2026-11-01T00:00:00Z",
      "credit_type_id": "ct_0001",
      "usd_cents_per_credit": "1",
      "recurring_credits": [
        {
          "allocation": "seat",
          "seat_tier": "standard",
          "amount": "1000",
          "credit_type_id": "ct_0001",
          "frequency": "MONTHLY",
          "recurring_credit_id": "rcr_0001",
          "status": "active"
        }
      ],
      "prepaid_balance_threshold_configuration": {
        "is_enabled": true,
        "threshold_amount": "100",
        "recharge_to_amount": "500",
        "credit_type_id": "ct_0001",
        "payment_gate_config": {
          "payment_gate_type": "EXTERNAL"
        }
      },
      "usage_statement_schedule": {
        "frequency": "MONTHLY"
      },
      "contract_id": "ctr_0001",
      "status": "scheduled",
      "version": 1,
      "subscriptions": [
        {
          "seat_tier": "standard",
          "quantity": 10,
          "unit_price_cents": 3000,
          "billing_frequency": "MONTHLY",
          "subscription_id": "sub_0001",
          "unassigned_seats": 1
        }
      ],
      "budgets": [
        {
          "scope": "customer",
          "amount": "1000",
          "credit_type_id": "ct_0001",
          "period": "MONTH",
          "mode": "hard",
          "budget_id": "bgt_0001"
        }
      ],
      "created_at": "2026-11-01T00:00:00Z"
    }
  ],
  "meta": {
    "request_id": "req_0001",
    "next_page": "page_0002"
  }
}

Errors 6

End a contract

POST/v1/contracts/{id}/end

Scope: admin
Portal tokens: Not allowed
Returns: The contract with its new ending_before.

Parameters
Name	Type	Description
`id`required	stringin path	Id of the resource named in the path.
`Idempotency-Key`required	stringin header	Unique per logical operation. Lives 48 hours. The same key with a different body is 409 `idempotency_conflict`. Min length `1`Max length `255`

Request body 1

Response fields 24

Request

curl -X POST https://api.example.invalid/v1/contracts/ctr_0001/end \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: idem_0001" \
  -d '{
  "ending_before": "2026-12-01T00:00:00Z"
}'

Response 200

{
  "data": {
    "customer_id": "cus_0001",
    "rate_card_id": "rc_0001",
    "starting_at": "2026-11-01T00:00:00Z",
    "credit_type_id": "ct_0001",
    "usd_cents_per_credit": "1",
    "recurring_credits": [
      {
        "allocation": "seat",
        "seat_tier": "standard",
        "amount": "1000",
        "credit_type_id": "ct_0001",
        "frequency": "MONTHLY",
        "recurring_credit_id": "rcr_0001",
        "status": "active"
      }
    ],
    "prepaid_balance_threshold_configuration": {
      "is_enabled": true,
      "threshold_amount": "100",
      "recharge_to_amount": "500",
      "credit_type_id": "ct_0001",
      "payment_gate_config": {
        "payment_gate_type": "EXTERNAL"
      }
    },
    "usage_statement_schedule": {
      "frequency": "MONTHLY"
    },
    "contract_id": "ctr_0001",
    "status": "scheduled",
    "version": 1,
    "subscriptions": [
      {
        "seat_tier": "standard",
        "quantity": 10,
        "unit_price_cents": 3000,
        "billing_frequency": "MONTHLY",
        "subscription_id": "sub_0001",
        "unassigned_seats": 1
      }
    ],
    "budgets": [
      {
        "scope": "customer",
        "amount": "1000",
        "credit_type_id": "ct_0001",
        "period": "MONTH",
        "mode": "hard",
        "budget_id": "bgt_0001"
      }
    ],
    "created_at": "2026-11-01T00:00:00Z"
  },
  "meta": {
    "request_id": "req_0001"
  }
}

Errors 8

Archive a contract

POST/v1/contracts/{id}/archive

Scope: admin
Portal tokens: Not allowed
Returns: The archived contract.

Parameters
Name	Type	Description
`id`required	stringin path	Id of the resource named in the path.
`Idempotency-Key`required	stringin header	Unique per logical operation. Lives 48 hours. The same key with a different body is 409 `idempotency_conflict`. Min length `1`Max length `255`

Response fields 24

Request

curl -X POST https://api.example.invalid/v1/contracts/ctr_0001/archive \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: idem_0001"

Response 200

{
  "data": {
    "customer_id": "cus_0001",
    "rate_card_id": "rc_0001",
    "starting_at": "2026-11-01T00:00:00Z",
    "credit_type_id": "ct_0001",
    "usd_cents_per_credit": "1",
    "recurring_credits": [
      {
        "allocation": "seat",
        "seat_tier": "standard",
        "amount": "1000",
        "credit_type_id": "ct_0001",
        "frequency": "MONTHLY",
        "recurring_credit_id": "rcr_0001",
        "status": "active"
      }
    ],
    "prepaid_balance_threshold_configuration": {
      "is_enabled": true,
      "threshold_amount": "100",
      "recharge_to_amount": "500",
      "credit_type_id": "ct_0001",
      "payment_gate_config": {
        "payment_gate_type": "EXTERNAL"
      }
    },
    "usage_statement_schedule": {
      "frequency": "MONTHLY"
    },
    "contract_id": "ctr_0001",
    "status": "scheduled",
    "version": 1,
    "subscriptions": [
      {
        "seat_tier": "standard",
        "quantity": 10,
        "unit_price_cents": 3000,
        "billing_frequency": "MONTHLY",
        "subscription_id": "sub_0001",
        "unassigned_seats": 1
      }
    ],
    "budgets": [
      {
        "scope": "customer",
        "amount": "1000",
        "credit_type_id": "ct_0001",
        "period": "MONTH",
        "mode": "hard",
        "budget_id": "bgt_0001"
      }
    ],
    "created_at": "2026-11-01T00:00:00Z"
  },
  "meta": {
    "request_id": "req_0001"
  }
}

Errors 7

Seats

Add seats to a contract

POST/v1/contracts/{id}/seats

Convenience wrapper for POST /v1/contracts/{id}/edits seat_updates.add_seat_ids. Proration and credit grant follow the contract's subscription and recurring credit settings.

Scope: admin
Portal tokens: Not allowed
Returns: The added seats, or the stored response on a replay.

Parameters
Name	Type	Description
`id`required	stringin path	Id of the resource named in the path.
`Idempotency-Key`required	stringin header	Unique per logical operation. Lives 48 hours. The same key with a different body is 409 `idempotency_conflict`. Min length `1`Max length `255`

Request body 3

Response fields 8

Request

curl -X POST https://api.example.invalid/v1/contracts/ctr_0001/seats \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: idem_0001" \
  -d '{
  "subscription_id": "sub_0001",
  "seat_ids": [
    "seat_0001"
  ],
  "seat_tier": "standard"
}'

Response 200

{
  "data": [
    {
      "seat_id": "seat_0001",
      "contract_id": "ctr_0001",
      "subscription_id": "sub_0001",
      "seat_tier": "standard",
      "status": "active",
      "starting_at": "2026-11-01T00:00:00Z"
    }
  ],
  "meta": {
    "request_id": "req_0001"
  }
}

Errors 11

Change the tier of a seat

PATCH/v1/contracts/{id}/seats/{seat_id}

An upgrade adds the credit difference at once. A downgrade takes effect next period.

Scope: admin
Portal tokens: Not allowed
Returns: The updated seat.

Parameters
Name	Type	Description
`id`required	stringin path	Id of the resource named in the path.
`seat_id`required	stringin path	Tenant-side seat id, URL encoded.
`Idempotency-Key`required	stringin header	Unique per logical operation. Lives 48 hours. The same key with a different body is 409 `idempotency_conflict`. Min length `1`Max length `255`

Request body 1

Response fields 8

Request

curl -X PATCH https://api.example.invalid/v1/contracts/ctr_0001/seats/seat_0001 \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: idem_0001" \
  -d '{
  "seat_tier": "standard"
}'

Response 200

{
  "data": {
    "seat_id": "seat_0001",
    "contract_id": "ctr_0001",
    "subscription_id": "sub_0001",
    "seat_tier": "standard",
    "status": "active",
    "starting_at": "2026-11-01T00:00:00Z"
  },
  "meta": {
    "request_id": "req_0001"
  }
}

Errors 9

Remove a seat

DELETE/v1/contracts/{id}/seats/{seat_id}

Follows the contract's seat_removal_timing. Removal voids the seat's unused credit, and a refund happens only when refund_on_seat_removal is true.

Scope: admin
Portal tokens: Not allowed
Returns: The seat, with status pending_removal or removed.

Parameters
Name	Type	Description
`id`required	stringin path	Id of the resource named in the path.
`seat_id`required	stringin path	Tenant-side seat id, URL encoded.
`Idempotency-Key`required	stringin header	Unique per logical operation. Lives 48 hours. The same key with a different body is 409 `idempotency_conflict`. Min length `1`Max length `255`

Response fields 8

Request

curl -X DELETE https://api.example.invalid/v1/contracts/ctr_0001/seats/seat_0001 \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: idem_0001"

Response 200

{
  "data": {
    "seat_id": "seat_0001",
    "contract_id": "ctr_0001",
    "subscription_id": "sub_0001",
    "seat_tier": "standard",
    "status": "active",
    "starting_at": "2026-11-01T00:00:00Z"
  },
  "meta": {
    "request_id": "req_0001"
  }
}

Errors 8

Balances

List the balance of each seat

GET/v1/contracts/{id}/seat_balances

Scope: read
Portal tokens: Not allowed
Returns: A page of seat balances for the current period.

Parameters
Name	Type	Description
`id`required	stringin path	Id of the resource named in the path.
`limit`	integerin query	Page size. Default `25`Minimum `1`Maximum `100`
`next_page`	stringin query	Opaque cursor from `meta.next_page`.
`seat_id`	stringin query	Filter to one seat.

Response fields 10

Request

curl https://api.example.invalid/v1/contracts/ctr_0001/seat_balances \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json"

Response 200

{
  "data": [
    {
      "credit_type_id": "ct_0001",
      "posted": "500",
      "reserved": "20",
      "available": "480",
      "seat_id": "seat_0001",
      "seat_tier": "standard",
      "status": "active",
      "period_starting_at": "2026-11-01T00:00:00Z",
      "period_ending_before": "2026-12-01T00:00:00Z"
    }
  ],
  "meta": {
    "request_id": "req_0001",
    "next_page": "page_0002"
  }
}

Errors 6

Get the net balance of a customer

GET/v1/customers/{id}/balance

Scope: read
Portal tokens: Allowed
Returns: Posted, reserved, and available amounts.

Parameters
Name	Type	Description
`id`required	stringin path	Id of the resource named in the path.
`include_seats`	booleanin query	Also return per-seat balances. Default `false`

Response fields 7

Request

curl https://api.example.invalid/v1/customers/cus_0001/balance \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json"

Response 200

{
  "data": {
    "credit_type_id": "ct_0001",
    "posted": "500",
    "reserved": "20",
    "available": "480",
    "customer_id": "cus_0001",
    "pool": {
      "credit_type_id": "ct_0001",
      "posted": "500",
      "reserved": "20",
      "available": "480"
    }
  },
  "meta": {
    "request_id": "req_0001"
  }
}

Errors 8

Commits

Create a prepaid commit

POST/v1/contracts/{id}/commits

Prepaid money lives in the customer's one wallet. A gated commit stays pending_payment until collection succeeds, and funds the wallet only then.

Scope: admin
Portal tokens: Not allowed
Returns: Commit created, or the stored response on a replay.

Parameters
Name	Type	Description
`id`required	stringin path	Id of the resource named in the path.
`Idempotency-Key`required	stringin header	Unique per logical operation. Lives 48 hours. The same key with a different body is 409 `idempotency_conflict`. Min length `1`Max length `255`

Request body 10

Response fields 16

Request

curl -X POST https://api.example.invalid/v1/contracts/ctr_0001/commits \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: idem_0001" \
  -d '{
  "amount": "1000",
  "credit_type_id": "ct_0001"
}'

Response 200

{
  "data": {
    "amount": "1000",
    "credit_type_id": "ct_0001",
    "commit_id": "cmt_0001",
    "contract_id": "ctr_0001",
    "status": "pending_payment",
    "remaining": "1000",
    "created_at": "2026-11-01T00:00:00Z"
  },
  "meta": {
    "request_id": "req_0001"
  }
}

Errors 10

Create a free credit

POST/v1/contracts/{id}/credits

Scope: admin
Portal tokens: Not allowed
Returns: Credit created, or the stored response on a replay.

Parameters
Name	Type	Description
`id`required	stringin path	Id of the resource named in the path.
`Idempotency-Key`required	stringin header	Unique per logical operation. Lives 48 hours. The same key with a different body is 409 `idempotency_conflict`. Min length `1`Max length `255`

Request body 7

Response fields 12

Request

curl -X POST https://api.example.invalid/v1/contracts/ctr_0001/credits \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: idem_0001" \
  -d '{
  "amount": "1000",
  "credit_type_id": "ct_0001"
}'

Response 200

{
  "data": {
    "amount": "1000",
    "credit_type_id": "ct_0001",
    "credit_id": "crd_0001",
    "contract_id": "ctr_0001",
    "status": "active",
    "remaining": "1000",
    "created_at": "2026-11-01T00:00:00Z"
  },
  "meta": {
    "request_id": "req_0001"
  }
}

Errors 9

Record a manual entry on a commit

POST/v1/commits/{id}/manual_entries

Records an offline payment or a positive adjustment.

Scope: admin
Portal tokens: Not allowed
Returns: Entry recorded, or the stored response on a replay.

Parameters
Name	Type	Description
`id`required	stringin path	Id of the resource named in the path.
`Idempotency-Key`required	stringin header	Unique per logical operation. Lives 48 hours. The same key with a different body is 409 `idempotency_conflict`. Min length `1`Max length `255`

Request body 3

Response fields 6

Request

curl -X POST https://api.example.invalid/v1/commits/cmt_0001/manual_entries \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: idem_0001" \
  -d '{
  "amount": "1000",
  "credit_type_id": "ct_0001",
  "reason": "Goodwill adjustment"
}'

Response 200

{
  "data": {
    "manual_entry_id": "man_0001",
    "commit_id": "cmt_0001",
    "amount": "1000",
    "credit_type_id": "ct_0001",
    "reason": "Goodwill adjustment",
    "created_at": "2026-11-01T00:00:00Z"
  },
  "meta": {
    "request_id": "req_0001"
  }
}

Errors 7

Usage

Authorize a call before it runs

POST/v1/authorize

Decides admission in one database transaction. Business denial is HTTP 200 with allowed false and a reason. Only auth, parameter, and server failures use an error envelope.

The request carries the hold inputs: customer_id, seat_id, request_id, and the estimate. When allowed, the response carries hold_id, hold_status, hold_expires_at, and the legs held. Pass hold_id to POST /v1/ingest to settle the hold. A hold not settled by hold_expires_at expires, and ingest arriving later is billed without it.

The drawdown order is seat bucket, pool buckets by priority, prepaid, then overage when the contract sets allow_overage. Member, pool, and customer hard limits count the non-seat legs only. The first reason that applies is returned.

Replay on (tenant, customer_id, request_id) returns the first decision with replayed true. Retrying after a denial therefore needs a new request_id.

Overshoot bound: settled spend on a hard limit L stays under L + Σ max(actual - estimate, 0) over holds admitted before L was reached.

Scope: ingest
Portal tokens: Not allowed
Idempotency: request_id in the body, keyed on (tenant, customer_id, request_id). No Idempotency-Key header.
Returns: Decision, including business denial.

Request body 7

Response fields 11

Request

curl -X POST https://api.example.invalid/v1/authorize \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
  "request_id": "req_0001",
  "customer_id": "cus_0001",
  "seat_id": "seat_0001",
  "product_id": "prod_text_to_3d",
  "estimated_quantity": "1"
}'

Response 200

{
  "data": {
    "allowed": false,
    "reason": "insufficient_balance",
    "retry_after_ms": 1000,
    "replayed": false,
    "credit_type_id": "ct_0001",
    "estimated_cost": "20",
    "available": {
      "seat": "0",
      "pool": "5.5"
    }
  },
  "meta": {
    "request_id": "rid_0001"
  }
}

Errors 16

Ingest a batch of usage events

POST/v1/ingest

One transaction per event. Rating happens once. A named hold is settled, then the drawdown re-walks with the actual amount. Usage is never refused for lack of funds, because the work already happened. The prepaid leg is queued for the wallet after commit.

Per-event results, in request order:

accepted: stored, rated, and billed.
duplicate: same transaction_id and same body within 34 days. Not billed again.
conflict: same transaction_id as an event from an earlier batch with a different body. Not stored or billed, and the batch still returns 200.
rejected: failed a per-event check. Does not occupy the transaction_id.

The same transaction_id with different bodies inside one batch refuses the whole batch with 409 idempotency_conflict_in_batch and takes priority over everything else in the batch. The same transaction_id with the same body inside one batch is duplicate.

Late events inside the 34-day window whose period is closed are accepted and carried forward, with warning billed_via_carry_forward_adjustment and adjustment_invoice_id when known. The closed invoice never changes.

Scope: ingest
Portal tokens: Not allowed
Idempotency: transaction_id per event, deduped on (tenant, transaction_id) for 34 days. No Idempotency-Key header.
Returns: Per-event results. Conflicts and rejections are inside this body.

Request body 1

Response fields 1

Request

curl -X POST https://api.example.invalid/v1/ingest \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
  "events": [
    {
      "transaction_id": "txn_0001",
      "customer_id": "cus_0001",
      "seat_id": "seat_0001",
      "event_type": "text_to_3d",
      "timestamp": "2026-11-01T00:00:00Z",
      "properties": {
        "model": "example-model",
        "count": "1"
      },
      "hold_id": "hold_0001"
    }
  ]
}'

Response 200

{
  "data": {
    "results": [
      {
        "index": 0,
        "transaction_id": "txn_0001",
        "status": "accepted",
        "rated_amount": "20",
        "hold_id": "hold_0001",
        "legs": [
          {
            "type": "seat",
            "amount": "1000"
          }
        ]
      }
    ]
  },
  "meta": {
    "request_id": "req_0001"
  }
}

Errors 15

Get grouped usage for a customer

GET/v1/customers/{id}/usage

Scope: read
Portal tokens: Allowed
Returns: A page of usage rows.

Parameters
Name	Type	Description
`id`required	stringin path	Id of the resource named in the path.
`limit`	integerin query	Page size. Default `25`Minimum `1`Maximum `100`
`next_page`	stringin query	Opaque cursor from `meta.next_page`.
`starting_at`required	timestampin query
`ending_before`required	timestampin query
`group_by`	array of enumin query	Grouping dimensions. Values: `product_idseat_id`
`window_size`	enumin query	Values: `HOURDAYNONE`

Response fields 7

Request

curl 'https://api.example.invalid/v1/customers/cus_0001/usage?starting_at=2026-11-01T00%3A00%3A00Z&ending_before=2026-12-01T00%3A00%3A00Z' \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json"

Response 200

{
  "data": [
    {
      "window_start": "2026-11-01T00:00:00Z",
      "window_end": "2026-12-01T00:00:00Z",
      "quantity": "1000",
      "rated_amount": "20",
      "credit_type_id": "ct_0001"
    }
  ],
  "meta": {
    "request_id": "req_0001",
    "next_page": "page_0002"
  }
}

Errors 8

Alerts

List alerts

GET/v1/alerts

Scope: read
Portal tokens: Allowed
Returns: A page of alerts.

Parameters
Name	Type	Description
`limit`	integerin query	Page size. Default `25`Minimum `1`Maximum `100`
`next_page`	stringin query	Opaque cursor from `meta.next_page`.
`customer_id`	stringin query	Filter by customer. A portal token sees only its own customer.

Response fields 8

Request

curl https://api.example.invalid/v1/alerts \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json"

Response 200

{
  "data": [
    {
      "alert_id": "alt_0001",
      "name": "Low balance",
      "customer_id": "cus_0001",
      "alert_type": "spend_threshold_reached",
      "threshold": "100",
      "status": "active",
      "created_at": "2026-11-01T00:00:00Z"
    }
  ],
  "meta": {
    "request_id": "req_0001",
    "next_page": "page_0002"
  }
}

Errors 7

Create a threshold alert

POST/v1/alerts

Scope: admin
Portal tokens: Allowed
Returns: Alert created, or the stored response on a replay.

Parameters
Name	Type	Description
`Idempotency-Key`required	stringin header	Unique per logical operation. Lives 48 hours. The same key with a different body is 409 `idempotency_conflict`. Min length `1`Max length `255`

Request body 5

Response fields 8

Request

curl -X POST https://api.example.invalid/v1/alerts \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: idem_0001" \
  -d '{
  "name": "Low balance",
  "customer_id": "cus_0001",
  "alert_type": "spend_threshold_reached",
  "threshold": "100"
}'

Response 200

{
  "data": {
    "alert_id": "alt_0001",
    "name": "Low balance",
    "customer_id": "cus_0001",
    "alert_type": "spend_threshold_reached",
    "threshold": "100",
    "status": "active",
    "created_at": "2026-11-01T00:00:00Z"
  },
  "meta": {
    "request_id": "req_0001"
  }
}

Errors 9

Archive an alert

POST/v1/alerts/{id}/archive

Scope: admin
Portal tokens: Allowed
Returns: The archived alert.

Parameters
Name	Type	Description
`id`required	stringin path	Id of the resource named in the path.
`Idempotency-Key`required	stringin header	Unique per logical operation. Lives 48 hours. The same key with a different body is 409 `idempotency_conflict`. Min length `1`Max length `255`

Response fields 8

Request

curl -X POST https://api.example.invalid/v1/alerts/alt_0001/archive \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: idem_0001"

Response 200

{
  "data": {
    "alert_id": "alt_0001",
    "name": "Low balance",
    "customer_id": "cus_0001",
    "alert_type": "spend_threshold_reached",
    "threshold": "100",
    "status": "active",
    "created_at": "2026-11-01T00:00:00Z"
  },
  "meta": {
    "request_id": "req_0001"
  }
}

Errors 9

Invoices

List the invoices of a customer

GET/v1/customers/{id}/invoices

Scope: read
Portal tokens: Allowed
Returns: A page of invoices.

Parameters
Name	Type	Description
`id`required	stringin path	Id of the resource named in the path.
`limit`	integerin query	Page size. Default `25`Minimum `1`Maximum `100`
`next_page`	stringin query	Opaque cursor from `meta.next_page`.
`status`	enumin query	Values: `draftfinalizedvoid`

Response fields 15

Request

curl https://api.example.invalid/v1/customers/cus_0001/invoices \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json"

Response 200

{
  "data": [
    {
      "invoice_id": "inv_0001",
      "customer_id": "cus_0001",
      "contract_id": "ctr_0001",
      "type": "USAGE",
      "status": "draft",
      "period_starting_at": "2026-11-01T00:00:00Z",
      "period_ending_before": "2026-12-01T00:00:00Z",
      "line_items": [
        {
          "type": "seat_subscription",
          "unit_price": "0.02",
          "amount_cents": 3000
        }
      ],
      "subtotal_cents": 3000,
      "total_cents": 3000
    }
  ],
  "meta": {
    "request_id": "req_0001",
    "next_page": "page_0002"
  }
}

Errors 8

Preview the draft invoice of a period

GET/v1/customers/{id}/invoices/preview

Scope: read
Portal tokens: Allowed
Returns: A live draft invoice. Previewing writes nothing.

Parameters
Name	Type	Description
`id`required	stringin path	Id of the resource named in the path.
`starting_at`	timestampin query	Start of the billing period. Defaults to the current period.

Response fields 15

Request

curl https://api.example.invalid/v1/customers/cus_0001/invoices/preview \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json"

Response 200

{
  "data": {
    "invoice_id": "inv_0001",
    "customer_id": "cus_0001",
    "contract_id": "ctr_0001",
    "type": "USAGE",
    "status": "draft",
    "period_starting_at": "2026-11-01T00:00:00Z",
    "period_ending_before": "2026-12-01T00:00:00Z",
    "line_items": [
      {
        "type": "seat_subscription",
        "unit_price": "0.02",
        "amount_cents": 3000
      }
    ],
    "subtotal_cents": 3000,
    "total_cents": 3000
  },
  "meta": {
    "request_id": "req_0001"
  }
}

Errors 9

Get an invoice

GET/v1/invoices/{id}

Scope: read
Portal tokens: Allowed
Returns: The invoice.

Parameters
Name	Type	Description
`id`required	stringin path	Id of the resource named in the path.

Response fields 15

Request

curl https://api.example.invalid/v1/invoices/inv_0001 \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json"

Response 200

{
  "data": {
    "invoice_id": "inv_0001",
    "customer_id": "cus_0001",
    "contract_id": "ctr_0001",
    "type": "USAGE",
    "status": "draft",
    "period_starting_at": "2026-11-01T00:00:00Z",
    "period_ending_before": "2026-12-01T00:00:00Z",
    "line_items": [
      {
        "type": "seat_subscription",
        "unit_price": "0.02",
        "amount_cents": 3000
      }
    ],
    "subtotal_cents": 3000,
    "total_cents": 3000
  },
  "meta": {
    "request_id": "req_0001"
  }
}

Errors 7

Download an invoice as PDF

GET/v1/invoices/{id}/pdf

The one binary response in this API, so it has no JSON envelope. The request id is in the X-Request-Id header.

Scope: read
Portal tokens: Allowed
Returns: The PDF.

Parameters
Name	Type	Description
`id`required	stringin path	Id of the resource named in the path.

Request

curl https://api.example.invalid/v1/invoices/inv_0001/pdf \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  --output invoice.pdf

Response 200: binary application/pdf body, with no JSON envelope.

Errors 7

Void a finalized invoice

POST/v1/invoices/{id}/void

Only a finalized invoice can be voided. Void and collection race on the same invoice, and the first commit wins.

Voidable collection statuses: none, not_required, collection_queued (also cancels the queued request with no payment call), and failed (also cancels the payment).

Voiding a commit purchase invoice before payment cancels the commit.

Scope: admin
Portal tokens: Not allowed
Returns: The voided invoice.

Parameters
Name	Type	Description
`id`required	stringin path	Id of the resource named in the path.
`Idempotency-Key`required	stringin header	Unique per logical operation. Lives 48 hours. The same key with a different body is 409 `idempotency_conflict`. Min length `1`Max length `255`

Response fields 15

Request

curl -X POST https://api.example.invalid/v1/invoices/inv_0001/void \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: idem_0001"

Response 200

{
  "data": {
    "invoice_id": "inv_0001",
    "customer_id": "cus_0001",
    "contract_id": "ctr_0001",
    "type": "USAGE",
    "status": "draft",
    "period_starting_at": "2026-11-01T00:00:00Z",
    "period_ending_before": "2026-12-01T00:00:00Z",
    "line_items": [
      {
        "type": "seat_subscription",
        "unit_price": "0.02",
        "amount_cents": 3000
      }
    ],
    "subtotal_cents": 3000,
    "total_cents": 3000
  },
  "meta": {
    "request_id": "req_0001"
  }
}

Errors 10

Issue a credit note on a finalized invoice

POST/v1/invoices/{id}/credit_notes

Finalized invoices never change, so a correction is a credit note. Collection and refunds stay with the payment provider or you.

Scope: admin
Portal tokens: Not allowed
Returns: Credit note issued, or the stored response on a replay.

Parameters
Name	Type	Description
`id`required	stringin path	Id of the resource named in the path.
`Idempotency-Key`required	stringin header	Unique per logical operation. Lives 48 hours. The same key with a different body is 409 `idempotency_conflict`. Min length `1`Max length `255`

Request body 2

Response fields 6

Request

curl -X POST https://api.example.invalid/v1/invoices/inv_0001/credit_notes \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: idem_0001" \
  -d '{
  "amount_cents": 3000,
  "reason": "Goodwill adjustment"
}'

Response 200

{
  "data": {
    "credit_note_id": "cn_0001",
    "invoice_id": "inv_0001",
    "amount_cents": 3000,
    "reason": "Goodwill adjustment",
    "status": "issued",
    "created_at": "2026-11-01T00:00:00Z"
  },
  "meta": {
    "request_id": "req_0001"
  }
}

Errors 9

Webhooks

Register a webhook endpoint

POST/v1/webhook_endpoints

Deliveries are at-least-once and HMAC signed. The signing secret is returned only in this response.

Scope: admin
Portal tokens: Not allowed
Returns: Endpoint created, or the stored response on a replay.

Parameters
Name	Type	Description
`Idempotency-Key`required	stringin header	Unique per logical operation. Lives 48 hours. The same key with a different body is 409 `idempotency_conflict`. Min length `1`Max length `255`

Request body 2

Response fields 5

Request

curl -X POST https://api.example.invalid/v1/webhook_endpoints \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: idem_0001" \
  -d '{
  "url": "https://hooks.kestrel.example/usage-billing"
}'

Response 200

{
  "data": {
    "webhook_endpoint_id": "wh_0001",
    "url": "https://hooks.kestrel.example/usage-billing",
    "created_at": "2026-11-01T00:00:00Z"
  },
  "meta": {
    "request_id": "req_0001"
  }
}

Errors 6

List events

GET/v1/events

Pull view of the events sent to webhooks. Async failures with no synchronous error appear here.

Scope: read
Portal tokens: Not allowed
Returns: A page of events, newest first.

Parameters
Name	Type	Description
`limit`	integerin query	Page size. Default `25`Minimum `1`Maximum `100`
`next_page`	stringin query	Opaque cursor from `meta.next_page`.
`type`	enumin query	Values: `balance.lowtopup.succeededtopup.failedtopup.limit_reachedbudget.threshold_reachedpool.quota_reachedmember.limit_reachedcommit.activatedcustomer.state_changed`
`customer_id`	stringin query

Response fields 6

Request

curl https://api.example.invalid/v1/events \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json"

Response 200

{
  "data": [
    {
      "event_id": "evt_0001",
      "type": "balance.low",
      "data": {},
      "created_at": "2026-11-01T00:00:00Z"
    }
  ],
  "meta": {
    "request_id": "req_0001",
    "next_page": "page_0002"
  }
}

Errors 7

Portal

Issue a portal token for a customer

POST/v1/portal_sessions

The tenant's server calls this and hands the short-lived token to the customer's browser. The tenant secret key is never exposed.

Scope: admin
Portal tokens: Not allowed
Returns: Token issued, or the stored response on a replay.

Parameters
Name	Type	Description
`Idempotency-Key`required	stringin header	Unique per logical operation. Lives 48 hours. The same key with a different body is 409 `idempotency_conflict`. Min length `1`Max length `255`

Request body 1

Response fields 4

Request

curl -X POST https://api.example.invalid/v1/portal_sessions \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: idem_0001" \
  -d '{
  "customer_id": "cus_0001"
}'

Response 200

{
  "data": {
    "token": "portal_token_xxx",
    "customer_id": "cus_0001",
    "scope": "portal",
    "expires_at": "2026-12-01T00:00:00Z"
  },
  "meta": {
    "request_id": "req_0001"
  }
}

Errors 7