chatrail-dev Billing API

openapi: 3.2.0
info:
  title: ChatRail Billing API
  version: 1.0.0
  description: 'Send, schedule and receive WhatsApp messages through a linked-device session.


    **Two things the API is careful about, which shape every endpoint below.**


    *Accepted is not delivered.* A 202 means the message is durably stored and queued. Only the `status` field ever claims WhatsApp delivered anything, and `queued`, `submitted`, `sent`, `delivered` and `read` are deliberately distinct.


    *A retry must not send twice.* Send `Idempotency-Key` on every send. A replay returns the original response; a concurrent duplicate is told to retry rather than allowed to race.'
  contact:
    name: ChatRail
    url: https://www.chatrail.dev
servers:
- url: https://www.chatrail.dev
security:
- apiKey: []
tags:
- name: Billing
  description: Checkout, the customer portal and Creem webhooks.
paths:
  /v1/billing:
    get:
      summary: Get the billing account
      description: 'What Creem says about this workspace: customer, subscription, status and the current period. Distinct from the plan on `/v1/workspace`, which is what the workspace is actually entitled to and is never blocked on this being reachable.'
      tags:
      - Billing
      operationId: get_v1_billing
      responses:
        '200':
          description: The billing account, or the free-tier default if there is none yet.
      security:
      - session: []
  /v1/billing/regional-price:
    get:
      summary: The visitor's regional prices
      description: 'For the public pricing pages: the regional monthly price of each plan in a country (`?country=NG`, else the visitor''s location), or `regional: null` when there is none. It only shows the price; a workspace pays it once it pairs a WhatsApp number from that country.'
      tags:
      - Billing
      operationId: get_v1_billing_regional-price
      responses:
        '200':
          description: 'The prices for the visitor''s country, or `regional: null`.'
      security: []
  /v1/billing/plans:
    get:
      summary: List paid plans
      description: 'The plans a checkout can be started for, with the price. `purchasable` is false when the plan has no Creem product configured yet. `regional` gives the plan''s monthly price for workspaces that paired a WhatsApp number from a country with regional pricing. Before any number is paired it can be shown from the visitor''s location with `requires_number: true`, meaning it applies only once a number from that country is paired. Null otherwise.'
      tags:
      - Billing
      operationId: get_v1_billing_plans
      responses:
        '200':
          description: The paid plans, in the order shown on the pricing page.
      security:
      - session: []
  /v1/billing/checkout:
    post:
      summary: Start a checkout
      description: Returns a Creem-hosted checkout URL for the chosen paid plan. When the workspace has a paired number from a regional-pricing country, the checkout opens with that discount.
      tags:
      - Billing
      operationId: post_v1_billing_checkout
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                plan:
                  type: string
                  enum:
                  - core
                  - core_ai
                  - team
                return_path:
                  default: /settings/billing
                  type: string
                  maxLength: 200
              required:
              - plan
              additionalProperties: false
            example:
              plan: core_ai
              return_path: /settings/billing
      responses:
        '201':
          description: The checkout id and URL to redirect the browser to.
        '404':
          description: Billing is not configured for this workspace.
      security:
      - session: []
  /v1/billing/plan-change-check:
    post:
      summary: Check whether a plan change is possible
      description: Whether moving to the given plan is allowed, and if not, how many connected numbers would have to be disconnected first. A downgrade is refused rather than applied when it would strand a number over the target plan's limit, because the alternatives are a silently suspended number — whose linked device stops working and needs a QR re-scan — and a customer permanently exceeding the plan they pay for. Changes nothing and spends nothing, so it needs only `billing:read`.
      tags:
      - Billing
      operationId: post_v1_billing_plan-change-check
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                plan:
                  type: string
                  enum:
                  - core
                  - core_ai
                  - team
              required:
              - plan
              additionalProperties: false
            example:
              plan: core
      responses:
        '200':
          description: '`allowed: true`, or `allowed: false` with the limit, the current count and `mustDisconnect`.'
        '400':
          description: The plan is not one that can be bought.
      security:
      - session: []
  /v1/billing/portal:
    post:
      summary: Open the customer portal
      description: A Creem-hosted page to update payment details or cancel — self-serve.
      tags:
      - Billing
      operationId: post_v1_billing_portal
      responses:
        '200':
          description: The portal URL to redirect the browser to.
        '404':
          description: This workspace has no billing account yet.
      security:
      - session: []
  /v1/billing/crypto:
    get:
      summary: Crypto payment options
      description: 'Whether crypto checkout is available, the accepted coins, the prepaid price of each plan for 3 and 12 months (12 months costs 10), and this workspace''s prepaid period and newest unpaid order, if any. A crypto purchase is a prepaid block of months, not a subscription: a wallet cannot be charged again automatically. With a regional price, `price_usd` is the reduced price, `list_price_usd` the full one, and `regional` names the discount.'
      tags:
      - Billing
      operationId: get_v1_billing_crypto
      responses:
        '200':
          description: 'Options and status. `available: false` when crypto is not configured.'
      security:
      - session: []
  /v1/billing/crypto/checkout:
    post:
      summary: Start a crypto checkout
      description: Creates a NOWPayments invoice for a prepaid period and returns its URL. The plan is applied when NOWPayments reports the payment `finished`. Buying the same plan again extends the running period; a different plan, or a workspace paying by card, is refused.
      tags:
      - Billing
      operationId: post_v1_billing_crypto_checkout
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                plan:
                  type: string
                  enum:
                  - core
                  - core_ai
                  - team
                months:
                  anyOf:
                  - type: number
                    const: 3
                  - type: number
                    const: 12
                pay_currency:
                  type: string
                  pattern: ^[a-z0-9]{2,20}$
                return_path:
                  default: /settings/billing
                  type: string
                  maxLength: 200
              required:
              - plan
              - months
              - pay_currency
              additionalProperties: false
            example:
              plan: core_ai
              months: 12
              pay_currency: usdttrc20
              return_path: /dashboard/billing
      responses:
        '201':
          description: The order id and the invoice URL to redirect the browser to.
        '400':
          description: The plan, period or currency is not one that can be bought.
        '404':
          description: Crypto payments are not configured.
        '409':
          description: The workspace pays by card, or has a different plan prepaid.
      security:
      - session: []
components:
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: 'A workspace API key, `cr_live_…`. Server-side only: it carries workspace authority and must never reach a browser.'
    session:
      type: apiKey
      in: cookie
      name: chatrail_session
      description: Dashboard session cookie. Set by `/v1/auth/verify`.