---
title: "Create a subscription"
method: POST
path: "/v1/payments/create-subscription"
tags: ["Stripe Payments"]
---

# Create a subscription

`POST /v1/payments/create-subscription`

Creates a Stripe Subscription for recurring payments. Returns clientSecret for frontend payment confirmation.

## Request body

- CreateSubscriptionDto
  - `priceId` string, required — Stripe Price ID
  - `planId` string, required — Internal plan identifier
  - `email` string, required — Customer email
  - `userId` string, required — Firebase user ID
  - `webUserId` string — Web user ID from tracking system
  - `customerId` string — Existing Stripe Customer ID (if customer was created earlier)
  - `promotionCode` string — Stripe Promotion Code ID (promo_...) applied to the first invoice. If set, takes precedence over `coupon`.
  - `coupon` string — Stripe Coupon ID applied to the subscription (e.g. percent_off, duration once). Ignored if `promotionCode` is set.

## Response `200`

Subscription created successfully

- CreateSubscriptionResponseDto
  - `clientSecret` string, required — Client secret from subscription latest invoice
  - `subscriptionId` string, required — Stripe Subscription ID
  - `customerId` string, required — Stripe Customer ID

## Other responses

- `400` — Invalid request parameters or Stripe error

---

[API](https://skmtc.dev/miaai/apis/backend-template-api.md) · [All operations](https://skmtc.dev/miaai/apis/backend-template-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/miaai/backend-template-api/revisions/2a8d88a5124f/schema)