Skip to main content
POST
/
v1
/
subscriptions
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"
    }
}'

{
  "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
}

Documentation Index

Fetch the complete documentation index at: https://docs.stateset.com/llms.txt

Use this file to discover all available pages before exploring further.

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
​
coupon_id
string
Coupon to apply to subscription
​
shipping_address
object
Shipping address for physical subscriptions
​
metadata
object
Additional custom fields

​
Response

Returns the created subscription. 
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"
    }
}'

{
  "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
}