curl --location --request POST 'https://api.stateset.com/api/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"
}
}'
const subscription = await stateset.subscriptions.create({
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
}
Create Subscription
Create a recurring subscription for a customer
POST
/
api
/
v1
/
subscriptions
curl --location --request POST 'https://api.stateset.com/api/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"
}
}'
const subscription = await stateset.subscriptions.create({
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
}
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 withsubscriptions:write permissions.
Authorization: Bearer YOUR_API_KEY
Request Body
string
required
Customer ID for the subscription
string
required
Subscription plan ID
string
required
Subscription start date (ISO 8601)
string
required
Default payment method for automatic billing
integer
Number of subscriptions (default: 1)
string
Trial period end date (ISO 8601)
string
Date to anchor billing cycles (ISO 8601)
array
string
Coupon to apply to subscription
object
object
Additional custom fields
Response
Returns the created subscription.curl --location --request POST 'https://api.stateset.com/api/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"
}
}'
const subscription = await stateset.subscriptions.create({
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
}
โI