Create subscription product

📘
API Refs

Staging: Create subscription product

Request body

Name	Type	Description	Required
productName	string	Product name for display purposes	yes
productDescription	string	Detailed product description	no
plans	array	Array of pricing plans for this product	yes

Plan Object (CreatePlanDto)

Name	Type	Description	Required
name	string	Plan name for display purposes	yes
description	string	Detailed plan description	no
amount	number	Price amount in cents (e.g., 2999 = $29.99)	yes
currency	string	Currency code (ISO 4217 format, e.g., "usd")	yes
interval	enum	Billing interval: "day", "week", "month", or "year"	yes
intervalCount	number	Interval multiplier (e.g., 3 for quarterly with interval="month")	no (default: 1)

Billing Interval Patterns

Common Patterns:

Monthly: interval: "month", intervalCount: 1
Quarterly: interval: "month", intervalCount: 3
Semi-Annual: interval: "month", intervalCount: 6
Annual: interval: "year", intervalCount: 1
Bi-Annual: interval: "year", intervalCount: 2

Response

Success Response (201 Created)

Field	Type	Description
stripeProductId	string	Stripe product identifier
name	string	Product name
description	string	Product description
plans	array	Available pricing plans

Plan Response Object

Field	Type	Description
stripePriceId	string	Stripe price ID
amount	number	Price amount in cents
currency	string	Currency code
interval	string	Billing interval ("month", "year")

Response

{
  "stripeProductId": "prod_ExampleProductABC",
  "name": "Auto Insurance Plans",
  "description": "Comprehensive auto insurance coverage with multiple plan options",
  "plans": [
    {
      "stripePriceId": "price_ExamplePriceID456",
      "amount": 4999,
      "currency": "usd",
      "interval": "month"
    },
    {
      "stripePriceId": "price_ExamplePriceID789",
      "amount": 49999,
      "currency": "usd",
      "interval": "year"
    }
  ]
}

Description

This endpoint creates a new subscription product with one or more pricing plans. Products represent what you're selling (e.g., "Premium Insurance Coverage"), while plans define how you charge for it (e.g., "$49.99/month" or "$499.99/year").

You can create multiple plans for a single product to offer different billing intervals or pricing tiers. The intervalCount field allows for flexible billing schedules like quarterly (interval="month", intervalCount=3) or semi-annual (interval="month", intervalCount=6) billing.

Important Notes

Pricing Strategy: Higher intervalCount often comes with discounts (annual vs monthly)
Immutable Plans: Plans cannot be modified after creation - create new plans instead
Currency: All plans for a product should use the same currency
Amount: Always specify amounts in cents (multiply dollar amount by 100)

Error Responses

400 Bad Request: Invalid product or plan configuration
401 Unauthorized: Invalid or missing authorization token
403 Forbidden: Insufficient permissions