Elastic Path Subscriptions API

Elastic Path Subscriptions enables you to manage your subscriptions plans and pricing options, using offerings. Offerings can contain any combination of pricing options and a plan. When a customer chooses a pricing option, a subscription is created. ### Managing the Subscription LifecycleThe subscription lifecycle is the states that a subscription can go through when a customer subscribes to a service or a plan. A subscription can have the following states:- `pending`- `canceled`- `paused`- `resumed`#### Creating a pending subscription A subscription can be created in a `pending` state. This is useful for several reasons.- If there are subscriptions that require user setup or onboarding, for example, installing software or setting up preferences. This helps reduce shopper frustration during the onboarding process, as the shopper is not paying for a service that they cannot use yet.- When offering a free trial or promotion, keeping the subscription in a pending state until the trial or promotion starts or ends allows you to manage transitions more smoothly. - Before a subscription becomes active, you may need to verify the payment method or authorize the first payment. Keeping the subscription in a pending state allows time to complete these steps without activating the subscription.For a subscription with a `pending` state, you can also configure a `go_live_after` date. The subscription starts from the `go_live_after` date. This is useful as it ensures both the subscription provider and subscriber are clear about when a subscription officially begins. Once the `go_live_after` date is passed, the subscription becomes `active`, initiating the billing and payment runs. If a subscription is activated this way, you can see this in the `timestamp` meta. You can configure a `go_live_after` date to be a past date. This is useful, for example, for backdating a subscription or managing a delay in activating a subscription. Setting the `go_live_after` date in the past ensures the subscriptions timeline correctly aligns with the agreed-upon service start date. :::cautionAlthough, billing runs generate one invoice per subscription, if a `go_live_date` is set far in the past, multiple invoices could be generated over the course of several billing runs, which could be frustrating and confusing to your subscribers. :::See [create a subscription](/docs/api/subscriptions/create-subscription).#### Cancelling or pausing and resuming subscriptionsA subscriber can decide to cancel or pause and/or resume a subscription. The following example describes pausing or canceling and resuming a subscription.1. The subscriber pauses or cancels the subscription. - The subscription status is `active`. - either `paused` or `cancelled` is set to `true`. - either the `paused_at` or `cancelled_at` timestamp is populated with the date and time the subscription is paused or cancelled. - for cancelled subscriptions, `end_date` indicates when the subscription will expire and end.2. When the next billing run is due, the billing run checks the subscription state. If the subscription state is paused or cancelled then no invoice is created and the subscription status is updated to `inactive`.3. Subsequent billing runs skip that subscription completely as the subscription status is `inactive`.4. If the subscriber resumes the subscription: - either `paused` or `cancelled` is set to `false`. - the `resumed_at` timestamp is populated with the date and time the subscription is resumed.5. When the next billing run is due, the billing run checks the subscription state. If the `paused` or `cancelled` is set to `false` then the billing run creates an invoice.6. The payment run processes the invoice. Once the payment succeeds then the payment run updates the status of the subscription to `active`.### OrdersWhen a customer chooses a subscription, they need to add the subscription to a cart, checkout the cart and then pay for the order. 1. When a customer adds a subscription to cart, this is handled using the `Add subscription to cart` endpoint. 2. Once a subscription has been added to a cart, the [**Checkout API**](/docs/api/carts/checkout-api) converts the cart to an order. 3. Once the order is created, payment needs to be taken. This is handled by Elastic Path Payments Powered by Stripe. See [**Payments**](/docs/api/subscriptions/invoices#payments).