---
title: "Create subscription checkout"
method: POST
path: "/api/billing-subscriptions/create-checkout"
tags: ["billing_subscriptions"]
---

# Create subscription checkout

`POST /api/billing-subscriptions/create-checkout`

## Request

- Base URL: `https://beta.getsales.io/id/v1`
- URL: `https://beta.getsales.io/id/v1/api/billing-subscriptions/create-checkout`
- Auth: HTTP bearer and API key in header `Team-SID`

Start a self-serve purchase of an order (quote_billing_subscription_order first: the same body). DANGEROUS (charges money): a Paddle transaction is pre-created with one item per line and result carries the checkout the buyer pays in the Paddle overlay (the SPA opens it with client_side_token and paddle_environment). The recurring lines become one subscription with one renewal date; one-time credits ride this first payment only, and alone they make no subscription. team_sid names the workspace that gets the WHOLE pool on activation (its trial is released); omit it to buy floating and allocate by hand. A workspace already on a live paid subscription is refused (409 team_already_covered: change that subscription instead), unless the order is one-time credits alone. The row is born on the activated webhook: poll search afterwards. Owner only.

Contract:
- MCP tool `create_billing_subscription_checkout`, registry package `mcp.id/billing_subscriptions`, mount `id.billing`.
- Operation `action`, response envelope `action`.
- Flags: dangerous: the MCP layer gates it behind a preview/commit token, and the effect cannot be undone through this API.

## Request body

- CreateBillingSubscriptionCheckoutRequest: Request body of `create_billing_subscription_checkout`.
  - `currency` 'USD' | 'EUR' | 'GBP', required: USD, EUR or GBP.
  - `period` 'monthly' | 'annual', required: monthly, or annual (12 + 2 months).
  - `data` object: The data credits line; omit for none.
    - `credits` integer, required: Credits: 0, or a whole number from 1,000.
    - `mode` 'recurring' | 'one_time': recurring (every month, the default) or one_time (paid once; the credits live with the plan).
  - `linkedin` object: The LinkedIn sender profiles line; omit for none.
    - `accounts` integer, required: LinkedIn accounts to run (slots, not users); the per-account rate falls with the count, 188 to 300 is one package.
  - `email` object: The email inbox capacity line; omit for none.
    - `packages` object, required: How many packages of each size, 0 to 1,000 each; the capacity is their sum.
      - `100` integer: Packages of 100 inboxes.
      - `500` integer: Packages of 500 inboxes.
      - `2000` integer: Packages of 2,000 inboxes.
      - `10000` integer: Packages of 10,000 inboxes.
  - `team_sid` string, nullable: The workspace that takes the whole pool on activation; omit or null to buy floating (a partner's pool).

## Response `200`

`action` success envelope.

- CreateBillingSubscriptionCheckoutResponse
  - `success` true, required
  - `operation` 'action', required
  - `action` string, required: kebab-case verb; matches the route segment.
  - `item` unknown, required
  - `result` object, required
    - `checkout_url` string, nullable, required: Paddle's checkout link; inert without Paddle.js and the token below.
    - `paddle_transaction_id` string, nullable, required: The pre-created transaction (txn_...).
    - `client_side_token` string, nullable, required: The publishable token Paddle.js boots with; null when the deployment has none.
    - `paddle_environment` string, required: sandbox | production, from the base uri the server dials.
    - `quote` object, required: The order as priced: exactly what Paddle bills before tax.
      - `currency` string, required: USD | EUR | GBP, the order's.
      - `period` string, required: monthly | annual, the order's.
      - `book` string, required: The price book version the figures came from.
      - `lines` object[], required: One per resource ordered: line (linkedin | email | data), its count or packages, capacity, rate_minor, monthly_minor and invoice_minor (the amount per billing period).
      - `monthly_minor` integer, required: The recurring lines a month, before 12 + 2.
      - `recurring_invoice_minor` integer, required: The recurring invoice: the monthly sum, times 12 on annual.
      - `one_time_minor` integer, required: The one-time credits line, paid once.
      - `due_now_minor` integer, required: The first payment before tax and coupons: the recurring invoice plus the one-time line.
      - `has_recurring` boolean, required: false = one-time credits alone, which make no subscription.
      - `service_months` integer, nullable, required: 1, or 14 for 12 + 2; null when nothing recurs.
      - `grant_count` integer, required: How many monthly credit grants the period pays for (1, or 14).
      - `credit_expiry_days` integer, nullable, required: Days a granted lot lives: null = the credits live with the plan and burn when the workspace leaves it (an order that buys a plan, or credits bought alone under one); 90 for credits bought alone with no paid plan.
      - `capacity` object, required: What the order grants a workspace: linkedin_sender_profiles, email_inboxes, credits_per_month, whitelabel.
      - `service` object, required: level (free | paid | business | enterprise), next_level, next_threshold_minor and gap_minor a month to it; White label is part of Business.
      - `linkedin_next_tier` object, nullable, required: The next LinkedIn volume tier: accounts, add, capacity, total_minor, per_account_minor, savings_minor (negative = costlier in total); null at the package and above.
    - `has_subscription` boolean, required: false = one-time credits alone: the credits land on the transaction, no subscription is born.
    - `pending` object, required: When the committed state lands: the activated webhook, or the completed transaction for one-time credits.
  - `meta` object, required
    - `trace_id` string, required: UUID v7; same 128-bit value as the X-Trace-Id header.
    - `span_id` string, required: 16 hex chars, root span of this request.
    - `timestamp` string, required: ISO 8601 UTC (Y-m-dTH:i:sZ), response time.
    - `duration_ms` integer, required: Server-side wall clock.
    - `team_sid` string, nullable: The team this call ran in (the token team, or the team_sid override). Null when unauthenticated; absent from pre-2026-08-20 backends.
    - `actor_type` string, nullable: user | agent | api_key | system. Null when unauthenticated; absent from pre-2026-08-20 backends.

## Other responses

- `4XX`: MCP error envelope. `error.code` is one of validation_failed, nothing_to_update, not_found, relation_not_found, invalid_transition, limit_exceeded, payment_required, duplicate_rejected, conflict, delete_blocked, unauthorized, forbidden, rate_limited, not_implemented.
- `5XX`: MCP error envelope with `error.code` internal_error or service_unavailable.

---

[API](https://skmtc.dev/getsales/apis/getsales-public-contract-gs-service-id.md) - [All operations](https://skmtc.dev/getsales/apis/getsales-public-contract-gs-service-id/llms.txt) - [OpenAPI document](https://skmtc.dev/getsales/apis/getsales-public-contract-gs-service-id/revisions/95e48541fe85?raw)