Skip to main content

Subscriptions

Elastic Path Subscriptions enables you to manage your subscriptions products and plans, using offerings. Offerings can contain any combination of plans and a product. When a customer chooses a plan, a subscription is created.

Managing the Subscription Lifecycle​

The subscription lifecycle is the states that a subscription can go through when a customer subscribes to a service or a product.

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.

caution

Although, 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.

Cancelling or pausing and resuming subscriptions​

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

Orders​

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