Create Subscription

Create a recurring subscription for a customer

This endpoint creates a new subscription for recurring billing. Subscriptions automatically generate invoices and process payments based on the billing cycle.

Authentication

This endpoint requires a valid API key with subscriptions:write permissions.

Authorization: Bearer YOUR_API_KEY

Request Body

customer_id · string · required

Customer ID for the subscription

plan_id · string · required

Subscription plan ID

start_date · string · required

Subscription start date (ISO 8601)

payment_method_id · string · required

Default payment method for automatic billing

quantity · integer

Number of subscriptions (default: 1)

trial_end · string

Trial period end date (ISO 8601)

billing_cycle_anchor · string

Date to anchor billing cycles (ISO 8601)

items · array

Additional subscription items

Show Item properties

product_id · string · required

Product ID

quantity · integer · required

Quantity

price_override · integer

Override price in cents

coupon_id · string

Coupon to apply to subscription

shipping_address · object

Shipping address for physical subscriptions

Show Address properties

line1 · string · required

Street address

line2 · string

Apartment/Suite

city · string · required

City

state · string · required

State/Province

postal_code · string · required

Postal code

country · string · required

Country code

metadata · object

Additional custom fields

Response

Returns the created subscription.

cURL

curl --location --request POST 'https://api.stateset.com/v1/subscriptions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data-raw '{
    "customer_id": "cust_abc123",
    "plan_id": "plan_monthly_pro",
    "start_date": "2024-02-01",
    "payment_method_id": "pm_card_visa",
    "trial_end": "2024-02-14",
    "items": [
        {
            "product_id": "prod_addon_storage",
            "quantity": 2
        }
    ],
    "shipping_address": {
        "line1": "123 Main St",
        "city": "Los Angeles",
        "state": "CA",
        "postal_code": "90001",
        "country": "US"
    }
}'

Response

{
  "id": "sub_0901f083-aa1c-43c5-af5c-0a9d2fc64e30",
  "object": "subscription",
  "customer_id": "cust_abc123",
  "status": "trialing",
  "created_at": "2024-01-19T17:00:00Z",
  "start_date": "2024-02-01",
  "current_period_start": "2024-02-01",
  "current_period_end": "2024-03-01",
  "trial_start": "2024-02-01",
  "trial_end": "2024-02-14",
  "plan": {
    "id": "plan_monthly_pro",
    "name": "Professional Monthly",
    "amount": 9900,
    "currency": "USD",
    "interval": "month",
    "interval_count": 1
  },
  "items": [
    {
      "id": "si_123456",
      "product_id": "prod_addon_storage",
      "product_name": "Additional Storage (10GB)",
      "quantity": 2,
      "unit_price": 500,
      "amount": 1000
    }
  ],
  "quantity": 1,
  "subtotal": 10900,
  "tax_amount": 872,
  "total_amount": 11772,
  "payment_method_id": "pm_card_visa",
  "default_payment_method": {
    "id": "pm_card_visa",
    "type": "card",
    "card": {
      "brand": "visa",
      "last4": "4242",
      "exp_month": 12,
      "exp_year": 2025
    }
  },
  "shipping_address": {
    "line1": "123 Main St",
    "city": "Los Angeles",
    "state": "CA",
    "postal_code": "90001",
    "country": "US"
  },
  "next_invoice_date": "2024-03-01",
  "cancel_at_period_end": false
}