WORKING
Billing
post
/v1/billing/subscriptionsCreate a Business's SaaS subscription
Parameters
| optional |
Request body
| Field | Type | Required |
|---|---|---|
| businessId | string (uuid) | yes |
| billingEmail | string (email) | yes |
| tier | SANDBOX | STARTER | GROWTH | ENTERPRISE | yes |
Response (201)
| Field | Type | Required |
|---|---|---|
| id | string (uuid) | — |
| businessId | string (uuid) | — |
| tier | SANDBOX | STARTER | GROWTH | ENTERPRISE | — |
| stripeSubscriptionId | stringnull | — |
| stripeCustomerId | stringnull | — |
| status | string | — |
| currentPeriodStart | string,null (date-time) | — |
| currentPeriodEnd | string,null (date-time) | — |
get
/v1/billing/subscriptions/{businessId}Get a Business's current active SaaS subscription
Parameters
| businessId | path | required |
Response (200)
| Field | Type | Required |
|---|---|---|
| id | string (uuid) | — |
| businessId | string (uuid) | — |
| tier | SANDBOX | STARTER | GROWTH | ENTERPRISE | — |
| stripeSubscriptionId | stringnull | — |
| stripeCustomerId | stringnull | — |
| status | string | — |
| currentPeriodStart | string,null (date-time) | — |
| currentPeriodEnd | string,null (date-time) | — |
post
/v1/billing/subscriptions/{businessId}/change-tierChange a Business's subscription tier
Parameters
| businessId | path | required |
| optional |
Request body
| Field | Type | Required |
|---|---|---|
| tier | SANDBOX | STARTER | GROWTH | ENTERPRISE | yes |
Response (201)
| Field | Type | Required |
|---|---|---|
| id | string (uuid) | — |
| businessId | string (uuid) | — |
| tier | SANDBOX | STARTER | GROWTH | ENTERPRISE | — |
| stripeSubscriptionId | stringnull | — |
| stripeCustomerId | stringnull | — |
| status | string | — |
| currentPeriodStart | string,null (date-time) | — |
| currentPeriodEnd | string,null (date-time) | — |
post
/v1/billing/subscriptions/{businessId}/cancelCancel a Business's subscription
Parameters
| businessId | path | required |
| optional |
Response (201)
| Field | Type | Required |
|---|---|---|
| id | string (uuid) | — |
| businessId | string (uuid) | — |
| tier | SANDBOX | STARTER | GROWTH | ENTERPRISE | — |
| stripeSubscriptionId | stringnull | — |
| stripeCustomerId | stringnull | — |
| status | string | — |
| currentPeriodStart | string,null (date-time) | — |
| currentPeriodEnd | string,null (date-time) | — |
post
/v1/billing/usageRecord a metered usage event for a merchant (internal — called by other services, not typically by merchants directly)
Request body
| Field | Type | Required |
|---|---|---|
| merchantId | string (uuid) | yes |
| eventType | LISTING_SYNC | SEARCH | OFFER | TRADE_SESSION | WEBHOOK_DELIVERY | CHECKOUT_ORCHESTRATION | yes |
| scope | INTRA_MERCHANT | CROSS_MERCHANT | yes |
| quantity | integer | — |
get
/v1/billing/usage/{businessId}A Business's current (or specified) billing-period metered usage, aggregated across every Merchant linked to it, including the cross-merchant multiplier breakdown and priced overage per event type. See docs/business/pricing.md.
Parameters
| businessId | path | required |
| billingPeriodRef | query | optional |
Response (200)
| Field | Type | Required |
|---|---|---|
| businessId | string (uuid) | — |
| merchantIds | string[] | — |
| tier | SANDBOX | STARTER | GROWTH | ENTERPRISE | — |
| billingPeriodRef | string | — |
| basePriceUsd | numbernull | — |
| lineItems | object[] | — |
| totalOverageUsd | number | — |
get
/v1/billing/statements/{businessId}Consolidated Business billing statement — merchantPlan (owed) and spaceEarnings (already paid out, net of commission) as two separate sections, never merged into one number. See docs/business/conflict-resolution-log.md item 20.
Parameters
| businessId | path | required |
| billingPeriodRef | query | optional |
Response (200)
| Field | Type | Required |
|---|---|---|
| businessId | string (uuid) | — |
| merchantPlan | UsageSummary | — |
| spaceEarnings | object | — |