---
title: "Create a subscription"
method: POST
path: "/v1/subscriptions"
tags: ["Subscriptions"]
---

# Create a subscription

`POST /v1/subscriptions`

## Request body

- CreateSubscriptionRequest — Subscription details
  - `clientReferenceId` string, required
  - `productId` string, required
  - `priceId` string, required
  - `customer` object, required
    - `id` string, required
  - `trial` object
    - `duration` integer, required
    - `durationType` 'hour' | 'day' | 'week' | 'month' | 'year', required
  - `discountedTrial` object — Deprecated: use `phases` instead.
    - `cycleCount` integer, required
    - `billingCycleConfig` object, required
      - `interval` 'hour' | 'day' | 'week' | 'month' | 'year', required
      - `frequency` integer, required
    - `price` object, required
      - `amountStr` string
      - `unitAmount` integer — Positive minor units / cents (e.g., currency: "USD", unitAmount: 10000 = USD 100). Mutually exclusive with amountStr.
      - `currency` 'USD' | 'AUD' | 'CAD' | 'CHF' | 'DKK' | 'EUR' | 'GBP' | 'HKD' | 'JPY' | 'NOK' | 'NZD' | 'PLN' | 'SEK' | 'SGD' | 'TWD' | 'KRW' | 'SOL' | 'USDC' | 'USDT' | 'HONEY' | 'EURC', required
  - `startAt` integer
  - `gracePeriodDays` integer — Number of days after an invoice's due date before the subscription lapses for non-payment. When set, overrides the merchant-level grace period for this subscription; when omitted, the merchant setting (else the platform default) applies. Maximum 90 days.
  - `successReturnUrl` string
  - `failReturnUrl` string
  - `preferredPaymentMethods` string[]
  - `phases` union[] — Optional ordered pricing phases. Each phase bills its own price for a fixed number of billing cycles before advancing to the next phase; once all phases are exhausted the subscription falls back to its default price (the top-level `priceId`). Cannot be combined with `discountedTrial`.
    - union
      - object
        - `cycleCount` integer, required — Number of billing cycles this phase bills before advancing to the next phase. After the final phase is exhausted, the subscription falls back to its default price.
        - `priceId` string, required — ID of an existing price to bill during this phase. The price must be active, recurring, belong to the same product as the subscription, and use the subscription's currency.
      - object
        - `cycleCount` integer, required — Number of billing cycles this phase bills before advancing to the next phase. After the final phase is exhausted, the subscription falls back to its default price.
        - `price` object, required — Inline price to bill during this phase, used instead of referencing an existing price by ID.
          - `unitAmount` integer, required — Amount in minor units / cents (e.g., 10000 = USD 100.00).
          - `currency` 'USD' | 'AUD' | 'CAD' | 'CHF' | 'DKK' | 'EUR' | 'GBP' | 'HKD' | 'JPY' | 'NOK' | 'NZD' | 'PLN' | 'SEK' | 'SGD' | 'TWD' | 'KRW' | 'SOL' | 'USDC' | 'USDT' | 'HONEY' | 'EURC', required — Currency for this phase. Must match the subscription's currency.
          - `billingCycleConfig` object, required
            - `interval` 'hour' | 'day' | 'week' | 'month' | 'year', required — Billing interval. Hourly billing (`hour`) is not supported in live mode.
            - `frequency` integer, required

## Response `200`

Success

- object — The created subscription
  - `status` 'SUCCEEDED', required
  - `data` CreateSubscriptionResponse, required
    - `id` string
    - `url` string

## Other responses

- `400` — Bad request
- `401` — Unauthorized

---

[API](https://skmtc.dev/breeze/apis/breeze-api.md) · [All operations](https://skmtc.dev/breeze/apis/breeze-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/breeze/breeze-api/revisions/8911892bdf29/schema)