Billing
Plans, subscription, invoices, usage.
11 نقطة وصول. أسماء نقاط الوصول وأوصافها مأخوذة من ملف OpenAPI، لذلك تظهر بالإنجليزية.
GET /v1/billing/plansGET /v1/billing/subscriptionPOST /v1/billing/checkoutPOST /v1/billing/change-planPOST /v1/billing/change-plan/previewPOST /v1/billing/cancelPOST /v1/billing/resumeGET /v1/billing/invoicesGET /v1/billing/portalPOST /v1/billing/webhooks/{provider}GET /v1/usage
GET
/v1/billing/plansPublic plan list (no auth)
لا يحتاج إلى مفتاح
الردود
- 200Successful Response
PlanOut[]
GET
/v1/billing/subscriptionBilling Subscription
يحتاج إلى مفتاح أو جلسة في لوحة التحكم
الردود
- 200Successful Response
SubscriptionOut
POST
/v1/billing/checkoutBilling Checkout
يحتاج إلى مفتاح أو جلسة في لوحة التحكم
المعاملات
| الاسم | الموضع | النوع | إلزامي | الوصف |
|---|---|---|---|---|
Idempotency-Key | header | string | null | لا | Unique per logical write (8-255 chars). Retries with the same key are safe. · pattern ^[A-Za-z0-9_\-:.]{8,255}$ |
جسم الطلب application/json CheckoutRequest
| الاسم | النوع | إلزامي | الوصف |
|---|---|---|---|
plan_code | string | نعم | max length 32 |
interval | "month" | "year" | لا | default "month" |
quantity | integer | لا | Plans sold by size (Enterprise): blocks of `sizing.block_products` products, 1 to 40. 1 for every other plan.default 1 · min 1 · max 40 |
الردود
- 200Successful Response
RedirectUrl
POST
/v1/billing/change-planUpgrade or downgrade with proration
يحتاج إلى مفتاح أو جلسة في لوحة التحكم
المعاملات
| الاسم | الموضع | النوع | إلزامي | الوصف |
|---|---|---|---|---|
Idempotency-Key | header | string | null | لا | Unique per logical write (8-255 chars). Retries with the same key are safe. · pattern ^[A-Za-z0-9_\-:.]{8,255}$ |
جسم الطلب application/json ChangePlanRequest
| الاسم | النوع | إلزامي | الوصف |
|---|---|---|---|
plan_code | string | نعم | max length 32 |
interval | "month" | "year" | لا | default "month" |
quantity | integer | لا | Plans sold by size (Enterprise): blocks of `sizing.block_products` products, 1 to 40. 1 for every other plan.default 1 · min 1 · max 40 |
الردود
- 200Successful Response
SubscriptionOut
POST
/v1/billing/change-plan/previewWhat a plan change charges today (nothing changes)
يحتاج إلى مفتاح أو جلسة في لوحة التحكم
جسم الطلب application/json ChangePlanRequest
| الاسم | النوع | إلزامي | الوصف |
|---|---|---|---|
plan_code | string | نعم | max length 32 |
interval | "month" | "year" | لا | default "month" |
quantity | integer | لا | Plans sold by size (Enterprise): blocks of `sizing.block_products` products, 1 to 40. 1 for every other plan.default 1 · min 1 · max 40 |
الردود
- 200Successful Response
ChangePlanPreview
POST
/v1/billing/cancelBilling Cancel
يحتاج إلى مفتاح أو جلسة في لوحة التحكم
جسم الطلب application/json CancelRequest
| الاسم | النوع | إلزامي | الوصف |
|---|---|---|---|
at_period_end | boolean | لا | Must be true: a store's plan runs to the end of the paid period (no refunds). false is refused with 403 cancel_now_not_allowed; only the super-admin console can end a plan now.default true |
reason | string | null | لا | max length 500 |
الردود
- 200Successful Response
SubscriptionOut
POST
/v1/billing/resumeKeep my plan: undo a cancel at period end before the period ends
يحتاج إلى مفتاح أو جلسة في لوحة التحكم
الردود
- 200Successful Response
SubscriptionOut
GET
/v1/billing/invoicesBilling Invoices
يحتاج إلى مفتاح أو جلسة في لوحة التحكم
الردود
- 200Successful Response
InvoiceOut[]
GET
/v1/billing/portalProvider portal (card, invoices)
يحتاج إلى مفتاح أو جلسة في لوحة التحكم
الردود
- 200Successful Response
RedirectUrl
POST
/v1/billing/webhooks/{provider}Payment provider webhooks (signature checked, no API key)
لا يحتاج إلى مفتاح
المعاملات
| الاسم | الموضع | النوع | إلزامي | الوصف |
|---|---|---|---|---|
provider | path | "paddle" | "stripe" | "mock" | نعم |
الردود
- 200Successful Response
map<string, boolean>
GET
/v1/usageUsage this period vs the plan
يحتاج إلى مفتاح أو جلسة في لوحة التحكم
الردود
- 200Successful Response
UsageOut
أشكال البيانات في هذه الصفحة
PlanOut
| الاسم | النوع | إلزامي | الوصف |
|---|---|---|---|
code | string | نعم | |
name | string | نعم | |
price_month_cents | integer | null | نعم | |
price_year_cents | integer | null | نعم | |
currency | string | نعم | |
products_limit | integer | null | نعم | null = custom |
searches_limit | integer | null | نعم | Searches per month (Enter). Suggest is never billed. |
features | object | نعم | |
overage | object | نعم | |
trial_days | integer | نعم | |
sizing | PlanSizing | null | لا | Set when the plan is bought by catalog size. |
PlanSizing
A plan bought by catalog size: price per month = graduated tiers on the number of blocks.
| الاسم | النوع | إلزامي | الوصف |
|---|---|---|---|
block_products | integer | نعم | Products in one block (the plan's products_limit). |
max_blocks | integer | نعم | Most blocks sold online. Above that: talk to sales. |
searches_per_extra_block | integer | نعم | Searches per month added by each block after the first. |
tiers | PriceTier[] | نعم |
PriceTier
| الاسم | النوع | إلزامي | الوصف |
|---|---|---|---|
up_to | integer | null | نعم | Last block of this tier. null = every block after the tiers before. |
month_cents | integer | نعم | Price per block per month in this tier. Yearly = 10 x. |
SubscriptionOut
| الاسم | النوع | إلزامي | الوصف |
|---|---|---|---|
plan_code | string | نعم | |
interval | "month" | "year" | نعم | |
status | "trialing" | "active" | "past_due" | "paused" | "canceled" | "incomplete" | نعم | |
provider | "paddle" | "stripe" | "mock" | "manual" | نعم | |
trial_ends_at | string (date-time) | null | لا | |
current_period_start | string (date-time) | null | لا | |
current_period_end | string (date-time) | null | لا | |
cancel_at_period_end | boolean | لا | default false |
quantity | integer | لا | Blocks of a plan sold by size (Enterprise); 1 for other plans.default 1 |
CheckoutRequest
| الاسم | النوع | إلزامي | الوصف |
|---|---|---|---|
plan_code | string | نعم | max length 32 |
interval | "month" | "year" | لا | default "month" |
quantity | integer | لا | Plans sold by size (Enterprise): blocks of `sizing.block_products` products, 1 to 40. 1 for every other plan.default 1 · min 1 · max 40 |
RedirectUrl
| الاسم | النوع | إلزامي | الوصف |
|---|---|---|---|
url | string | نعم |
ChangePlanRequest
| الاسم | النوع | إلزامي | الوصف |
|---|---|---|---|
plan_code | string | نعم | max length 32 |
interval | "month" | "year" | لا | default "month" |
quantity | integer | لا | Plans sold by size (Enterprise): blocks of `sizing.block_products` products, 1 to 40. 1 for every other plan.default 1 · min 1 · max 40 |
ChangePlanPreview
What POST /v1/billing/change-plan with the same body would charge today. Nothing changes.
| الاسم | النوع | إلزامي | الوصف |
|---|---|---|---|
plan_code | string | نعم | |
interval | "month" | "year" | نعم | |
quantity | integer | لا | default 1 |
proration | "prorate_now" | "prorate_next_invoice" | نعم | prorate_now: an upgrade, the difference is charged now. prorate_next_invoice: a downgrade, the credit goes on the next invoice. |
known | boolean | نعم | False: the amount is not known (see `reason`); confirm without an amount. |
amount_minor | integer | null | لا | Charged today in minor units (cents): the provider's amount for the plan change (tax included) plus add-on bundles at their list price. 0 = nothing is charged today. |
tax_minor | integer | null | لا | |
currency | string | null | لا | |
reason | "provider_has_no_preview" | "provider_error" | "addon_price_unknown" | null | لا | Why the amount is not known. None when `known` is true. |
CancelRequest
| الاسم | النوع | إلزامي | الوصف |
|---|---|---|---|
at_period_end | boolean | لا | Must be true: a store's plan runs to the end of the paid period (no refunds). false is refused with 403 cancel_now_not_allowed; only the super-admin console can end a plan now.default true |
reason | string | null | لا | max length 500 |
InvoiceOut
| الاسم | النوع | إلزامي | الوصف |
|---|---|---|---|
id | string | نعم | |
status | string | نعم | |
currency | string | نعم | |
total_minor | integer | نعم | |
tax_minor | integer | نعم | |
hosted_url | string | null | لا | |
pdf_url | string | null | لا | |
issued_at | string (date-time) | نعم | |
paid_at | string (date-time) | null | لا |
UsageOut
| الاسم | النوع | إلزامي | الوصف |
|---|---|---|---|
period_start | string (date) | نعم | |
period_end | string (date) | نعم | |
plan_code | string | null | نعم | null = the store has no plan yet (see TenantOut.billing_state). |
metrics | UsageMetric[] | نعم | |
overage_estimate_cents | integer | نعم | |
daily | UsageDay[] | نعم | |
notices | "80_percent" | "100_percent"[] | لا |
UsageMetric
| الاسم | النوع | إلزامي | الوصف |
|---|---|---|---|
metric | "search" | "translated_product" | "products_indexed" | نعم | |
used | integer | نعم | |
limit | integer | null | نعم | |
percent | number | null | نعم |
UsageDay
| الاسم | النوع | إلزامي | الوصف |
|---|---|---|---|
day | string (date) | نعم | |
searches | integer | نعم | |
suggests_not_billed | integer | نعم | |
translated_products | integer | نعم |