Billing
Plans, subscription, invoices, usage.
9 endpoints.
GET /v1/billing/plansGET /v1/billing/subscriptionPOST /v1/billing/checkoutPOST /v1/billing/change-planPOST /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/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" |
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" |
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 |
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 |
CheckoutRequest
| Name | Type | Required | Description |
|---|---|---|---|
plan_code | string | yes | max length 32 |
interval | "month" | "year" | no | default "month" |
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" |
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" | "translated_product" | "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 | |
translated_products | integer | yes |