---
title: "Start a subscription checkout"
method: POST
path: "/api/v1/billing/checkout/subscription"
tags: ["billing"]
---

# Start a subscription checkout

`POST /api/v1/billing/checkout/subscription`

Returns an embedded Stripe Checkout `clientSecret` to subscribe the account for the given `interval`. Quantity is set server-side to the account's current phone-number count (one unit per number) — Dial doesn't subscribe a subset. Coverage begins when the invoice is paid. Not available during impersonation.

Accounts holding an iMessage number can't subscribe — iMessage is pay-as-you-go only, so the request is rejected with `403`. Release the iMessage number first.

## Headers

- `Authorization` string, required

## Request body

- object
  - `interval` 'monthly' | 'annual', required
  - `returnUrl` string, uri — Where Checkout returns after completion. Defaults to the dashboard billing page.

## Response `200`

Embedded Checkout client secret.

- BillingCreateSubscriptionCheckoutResponse200
  - `clientSecret` string

## Other responses

- `400` — The request body failed validation.
- `401` — Missing or invalid API key.
- `403` — The account holds an iMessage number, which is pay-as-you-go only and can't be covered by a subscription. Release it before subscribing.

---

[API](https://skmtc.net/getdial/apis/rest-api.md) · [All operations](https://skmtc.net/getdial/apis/rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/getdial/rest-api/revisions/5f4eb30ac29a/schema)