Billing
Plans, subscription, invoices, usage.
11 نقطة وصول. أسماء نقاط الوصول وأوصافها مأخوذة من ملف OpenAPI، لذلك تظهر بالإنجليزية.
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)
لا يحتاج إلى مفتاح
الردود
- 200Successful Response
PlanOut[]
GET
/v1/billing/addonsPublic add-on list (assistant conversation bundles; no auth)
لا يحتاج إلى مفتاح
الردود
- 200Successful Response
AddonOut[]
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" |
addons | AddonQuantity[] | لا |
الردود
- 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" |
addons | AddonQuantity[] | لا | Extra bundles to buy now with the change. |
الردود
- 200Successful Response
SubscriptionOut
POST
/v1/billing/addons/purchaseBuy add-on bundles now (one-time charge)
يحتاج إلى مفتاح أو جلسة في لوحة التحكم
المعاملات
| الاسم | الموضع | النوع | إلزامي | الوصف |
|---|---|---|---|---|
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 AddonPurchaseRequest
| الاسم | النوع | إلزامي | الوصف |
|---|---|---|---|
code | string | نعم | max length 48 |
quantity | integer | لا | default 1 · min 1 · max 100 |
الردود
- 200Successful Response
SubscriptionOut
POST
/v1/billing/cancelBilling Cancel
يحتاج إلى مفتاح أو جلسة في لوحة التحكم
جسم الطلب application/json CancelRequest
| الاسم | النوع | إلزامي | الوصف |
|---|---|---|---|
at_period_end | boolean | لا | default true |
reason | string | null | لا | max length 500 |
الردود
- 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 | نعم |
AddonOut
An add-on from the catalog (table `addons`). price_month_cents null = price not set yet.
| الاسم | النوع | إلزامي | الوصف |
|---|---|---|---|
code | string | نعم | |
name | string | نعم | |
kind | "assistant_conversations" | نعم | |
bundle_size | integer | نعم | |
price_cents | integer | null | نعم | |
currency | string | نعم | |
plans | string[] | نعم | Plans that may buy it. |
expires | "period_end" | "never" | نعم |
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 |
addons | map<string, AddonBalance> | لا | Add-on code -> balance. |
AddonBalance
What the store has of one add-on in the current period.
| الاسم | النوع | إلزامي | الوصف |
|---|---|---|---|
units | integer | نعم | Bought this period (bundles x bundle size). |
used | integer | نعم | Counted from usage (metric assistant_conversation). |
remaining | integer | نعم | |
period_end | string (date-time) | null | لا |
CheckoutRequest
| الاسم | النوع | إلزامي | الوصف |
|---|---|---|---|
plan_code | string | نعم | max length 32 |
interval | "month" | "year" | لا | default "month" |
addons | AddonQuantity[] | لا |
AddonQuantity
| الاسم | النوع | إلزامي | الوصف |
|---|---|---|---|
code | string | نعم | max length 48 |
quantity | integer | نعم | Number of bundles.min 1 · max 100 |
RedirectUrl
| الاسم | النوع | إلزامي | الوصف |
|---|---|---|---|
url | string | نعم |
ChangePlanRequest
| الاسم | النوع | إلزامي | الوصف |
|---|---|---|---|
plan_code | string | نعم | max length 32 |
interval | "month" | "year" | لا | default "month" |
addons | AddonQuantity[] | لا | 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.
| الاسم | النوع | إلزامي | الوصف |
|---|---|---|---|
code | string | نعم | max length 48 |
quantity | integer | لا | default 1 · min 1 · max 100 |
CancelRequest
| الاسم | النوع | إلزامي | الوصف |
|---|---|---|---|
at_period_end | boolean | لا | 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 | نعم | |
metrics | UsageMetric[] | نعم | |
overage_estimate_cents | integer | نعم | |
daily | UsageDay[] | نعم | |
notices | "80_percent" | "100_percent"[] | لا |
UsageMetric
| الاسم | النوع | إلزامي | الوصف |
|---|---|---|---|
metric | "search" | "assistant_message" | "assistant_conversation" | "translated_product" | "ai_cost_micros_usd" | "products_indexed" | نعم | |
used | integer | نعم | |
limit | integer | null | نعم | |
percent | number | null | نعم |
UsageDay
| الاسم | النوع | إلزامي | الوصف |
|---|---|---|---|
day | string (date) | نعم | |
searches | integer | نعم | |
suggests_not_billed | integer | نعم | |
assistant_messages | integer | نعم | |
assistant_conversations | integer | نعم | |
translated_products | integer | نعم |