Managing subscriptions

Subscriptions allow you to charge a customer on a recurring basis. A subscription ties a customer to a particular plan you’ve created.

Create a subscription

Endpoint: POST /v1/subscriptions

Parameters:

customer (required): The identifier of the customer to subscribe.
items (required): A list of items the customer is subscribing to.
trial_period_days (optional): Integer representing the number of trial period days before the customer is charged for the first time.

Example request:

curl https://api.stripe.com/v1/subscriptions \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d customer="cus_Hh1aJLgbvgUEZJ" \
  -d "items[0][price]"="price_Hh1dKLBm3nJNJ4" \
  -d trial_period_days=15

Example response:

{
  "id": "sub_Hh1eWnUDLDtWk8",
  "object": "subscription",
  "application_fee_percent": null,
  "billing_cycle_anchor": 1604304000,
  "billing_thresholds": null,
  "cancel_at": null,
  "cancel_at_period_end": false,
  "canceled_at": null,
  "collection_method": "charge_automatically",
  "created": 1602689179,
  "current_period_end": 1604304000,
  "current_period_start": 1602689179,
  "customer": "cus_Hh1aJLgbvgUEZJ",
  "days_until_due": null,
  "default_payment_method": null,
  "default_source": null,
  "default_tax_rates": [],
  "discount": null,
  "ended_at": null,
  "items": {...},
  "latest_invoice": "in_1Hh1hmCm4uUe0pYsrjLHMQ0Y",
  "livemode": false,
  "metadata": {},
  "next_pending_invoice_item_invoice": null,
  "pause_collection": null,
  "pending_invoice_item_interval": null,
  "pending_setup_intent": null,
  "pending_update": null,
  "plan": {...},
  "quantity": 1,
  "schedule": null,
  "start_date": 1602689179,
  "status": "trialing",
  "transfer_data": null,
  "trial_end": 1604304000,
  "trial_start": 1602689179
```}