Billing
Plans, subscription, invoices, usage.
11 endpoints.
GET /v1/billing/plansGET /v1/billing/addonsGET /v1/billing/subscriptionPOST /v1/billing/checkoutPOST /v1/billing/change-planPOST /v1/billing/addons/purchasePOST /v1/billing/cancelGET /v1/billing/invoicesGET /v1/billing/portalPOST /v1/billing/webhooks/{provider}GET /v1/usage
GET
/v1/billing/plansPublic plan list (no auth)
No key needed
Responses
- 200Successful Response
PlanOut[]
GET
/v1/billing/addonsPublic add-on list (assistant conversation bundles; no auth)
No key needed
Responses
- 200Successful Response
AddonOut[]
GET
/v1/billing/subscriptionBilling Subscription
Needs a key or a dashboard session
Responses
- 200Successful Response
SubscriptionOut
POST
/v1/billing/checkoutBilling Checkout
Needs a key or a dashboard session
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | null | no | Unique per logical write (8-255 chars). Retries with the same key are safe. · pattern ^[A-Za-z0-9_\-:.]{8,255}$ |
Request body application/json CheckoutRequest
| Name | Type | Required | Description |
|---|---|---|---|
plan_code | string | yes | max length 32 |
interval | "month" | "year" | no | default "month" |
addons | AddonQuantity[] | no |
Responses
- 200Successful Response
RedirectUrl
POST
/v1/billing/change-planUpgrade or downgrade with proration
Needs a key or a dashboard session
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | null | no | Unique per logical write (8-255 chars). Retries with the same key are safe. · pattern ^[A-Za-z0-9_\-:.]{8,255}$ |
Request body application/json ChangePlanRequest
| Name | Type | Required | Description |
|---|---|---|---|
plan_code | string | yes | max length 32 |
interval | "month" | "year" | no | default "month" |
addons | AddonQuantity[] | no | Extra bundles to buy now with the change. |
Responses
- 200Successful Response
SubscriptionOut
POST
/v1/billing/addons/purchaseBuy add-on bundles now (one-time charge)
Needs a key or a dashboard session
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | null | no | Unique per logical write (8-255 chars). Retries with the same key are safe. · pattern ^[A-Za-z0-9_\-:.]{8,255}$ |
Request body application/json AddonPurchaseRequest
| Name | Type | Required | Description |
|---|---|---|---|
code | string | yes | max length 48 |
quantity | integer | no | default 1 · min 1 · max 100 |
Responses
- 200Successful Response
SubscriptionOut
POST
/v1/billing/cancelBilling Cancel
Needs a key or a dashboard session
Request body application/json CancelRequest
| Name | Type | Required | Description |
|---|---|---|---|
at_period_end | boolean | no | default true |
reason | string | null | no | max length 500 |
Responses
- 200Successful Response
SubscriptionOut
GET
/v1/billing/invoicesBilling Invoices
Needs a key or a dashboard session
Responses
- 200Successful Response
InvoiceOut[]
GET
/v1/billing/portalProvider portal (card, invoices)
Needs a key or a dashboard session
Responses
- 200Successful Response
RedirectUrl
POST
/v1/billing/webhooks/{provider}Payment provider webhooks (signature checked, no API key)
No key needed
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
provider | path | "paddle" | "stripe" | "mock" | yes |
Responses
- 200Successful Response
map<string, boolean>
GET
/v1/usageUsage this period vs the plan
Needs a key or a dashboard session
Responses
- 200Successful Response
UsageOut
Data shapes on this page
PlanOut
| Name | Type | Required | Description |
|---|---|---|---|
code | string | yes | |
name | string | yes | |
price_month_cents | integer | null | yes | |
price_year_cents | integer | null | yes | |
currency | string | yes | |
products_limit | integer | null | yes | null = custom |
searches_limit | integer | null | yes | Searches per month (Enter). Suggest is never billed. |
features | object | yes | |
overage | object | yes | |
trial_days | integer | yes |
AddonOut
An add-on from the catalog (table `addons`). price_month_cents null = price not set yet.
| Name | Type | Required | Description |
|---|---|---|---|
code | string | yes | |
name | string | yes | |
kind | "assistant_conversations" | yes | |
bundle_size | integer | yes | |
price_cents | integer | null | yes | |
currency | string | yes | |
plans | string[] | yes | Plans that may buy it. |
expires | "period_end" | "never" | yes |
SubscriptionOut
| Name | Type | Required | Description |
|---|---|---|---|
plan_code | string | yes | |
interval | "month" | "year" | yes | |
status | "trialing" | "active" | "past_due" | "paused" | "canceled" | "incomplete" | yes | |
provider | "paddle" | "stripe" | "mock" | "manual" | yes | |
trial_ends_at | string (date-time) | null | no | |
current_period_start | string (date-time) | null | no | |
current_period_end | string (date-time) | null | no | |
cancel_at_period_end | boolean | no | default false |
addons | map<string, AddonBalance> | no | Add-on code -> balance. |
AddonBalance
What the store has of one add-on in the current period.
| Name | Type | Required | Description |
|---|---|---|---|
units | integer | yes | Bought this period (bundles x bundle size). |
used | integer | yes | Counted from usage (metric assistant_conversation). |
remaining | integer | yes | |
period_end | string (date-time) | null | no |
CheckoutRequest
| Name | Type | Required | Description |
|---|---|---|---|
plan_code | string | yes | max length 32 |
interval | "month" | "year" | no | default "month" |
addons | AddonQuantity[] | no |
AddonQuantity
| Name | Type | Required | Description |
|---|---|---|---|
code | string | yes | max length 48 |
quantity | integer | yes | Number of bundles.min 1 · max 100 |
RedirectUrl
| Name | Type | Required | Description |
|---|---|---|---|
url | string | yes |
ChangePlanRequest
| Name | Type | Required | Description |
|---|---|---|---|
plan_code | string | yes | max length 32 |
interval | "month" | "year" | no | default "month" |
addons | AddonQuantity[] | no | Extra bundles to buy now with the change. |
AddonPurchaseRequest
Buy more bundles now (one-time charge). Needs a live subscription on a plan that allows it.
| Name | Type | Required | Description |
|---|---|---|---|
code | string | yes | max length 48 |
quantity | integer | no | default 1 · min 1 · max 100 |
CancelRequest
| Name | Type | Required | Description |
|---|---|---|---|
at_period_end | boolean | no | default true |
reason | string | null | no | max length 500 |
InvoiceOut
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | |
status | string | yes | |
currency | string | yes | |
total_minor | integer | yes | |
tax_minor | integer | yes | |
hosted_url | string | null | no | |
pdf_url | string | null | no | |
issued_at | string (date-time) | yes | |
paid_at | string (date-time) | null | no |
UsageOut
| Name | Type | Required | Description |
|---|---|---|---|
period_start | string (date) | yes | |
period_end | string (date) | yes | |
plan_code | string | yes | |
metrics | UsageMetric[] | yes | |
overage_estimate_cents | integer | yes | |
daily | UsageDay[] | yes | |
notices | "80_percent" | "100_percent"[] | no |
UsageMetric
| Name | Type | Required | Description |
|---|---|---|---|
metric | "search" | "assistant_message" | "assistant_conversation" | "translated_product" | "ai_cost_micros_usd" | "products_indexed" | yes | |
used | integer | yes | |
limit | integer | null | yes | |
percent | number | null | yes |
UsageDay
| Name | Type | Required | Description |
|---|---|---|---|
day | string (date) | yes | |
searches | integer | yes | |
suggests_not_billed | integer | yes | |
assistant_messages | integer | yes | |
assistant_conversations | integer | yes | |
translated_products | integer | yes |