> ## 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.

# Create Subscription

> Create a recurring subscription for a customer

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

## Authentication

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

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Request Body

<ParamField body="customer_id" type="string" required>
  Customer ID for the subscription
</ParamField>

<ParamField body="plan_id" type="string" required>
  Subscription plan ID
</ParamField>

<ParamField body="start_date" type="string" required>
  Subscription start date (ISO 8601)
</ParamField>

<ParamField body="payment_method_id" type="string" required>
  Default payment method for automatic billing
</ParamField>

<ParamField body="quantity" type="integer">
  Number of subscriptions (default: 1)
</ParamField>

<ParamField body="trial_end" type="string">
  Trial period end date (ISO 8601)
</ParamField>

<ParamField body="billing_cycle_anchor" type="string">
  Date to anchor billing cycles (ISO 8601)
</ParamField>

<ParamField body="items" type="array">
  Additional subscription items

  <Expandable title="Item properties">
    <ParamField body="product_id" type="string" required>
      Product ID
    </ParamField>

    <ParamField body="quantity" type="integer" required>
      Quantity
    </ParamField>

    <ParamField body="price_override" type="integer">
      Override price in cents
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="coupon_id" type="string">
  Coupon to apply to subscription
</ParamField>

<ParamField body="shipping_address" type="object">
  Shipping address for physical subscriptions

  <Expandable title="Address properties">
    <ParamField body="line1" type="string" required>
      Street address
    </ParamField>

    <ParamField body="line2" type="string">
      Apartment/Suite
    </ParamField>

    <ParamField body="city" type="string" required>
      City
    </ParamField>

    <ParamField body="state" type="string" required>
      State/Province
    </ParamField>

    <ParamField body="postal_code" type="string" required>
      Postal code
    </ParamField>

    <ParamField body="country" type="string" required>
      Country code
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="metadata" type="object">
  Additional custom fields
</ParamField>

### Response

Returns the created subscription.

<RequestExample>
  ```bash cURL theme={null}
  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"
      }
  }'
  ```

  ```javascript Node.js theme={null}
  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"
    }
  });
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "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
  }
  ```
</ResponseExample>