Skip to main content

Subscriptions

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 Lifecycle​

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

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, pausing, and resuming subscriptions​

A subscriber can cancel their own subscription, and can pause or resume it when the current pricing option's can_pause or can_resume allows it. A merchandizer can pause, resume, or cancel a subscription on a subscriber's behalf, regardless of those flags. The following example describes each lifecycle change.

Subscriber-initiated cancellation​
  1. The subscriber cancels the subscription.
    • The subscription status is active.
    • cancelled is set to true.
    • the cancelled_at timestamp is populated with the date and time the subscription was cancelled.
    • 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 is 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.
Subscriber-initiated pause and resume​
  1. The subscriber pauses the subscription. This request is rejected if the current pricing option's can_pause is false.
    • The subscription status is active.
    • paused is set to true.
    • the paused_at timestamp is populated with the date and time the subscription was paused.
    • paused_by is set to subscriber. This field is visible only to merchandizer and store or organization-scoped callers.
  2. When the next billing run is due, the billing run checks the subscription state. If the subscription is paused 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. The subscriber resumes the subscription. This request is rejected if the current pricing option's can_resume is false, or if paused_by is dunning or absent, meaning only a merchandizer can resume it instead.
    • paused 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 paused is set to false then the billing run creates an invoice.
  6. The payment run processes the invoice. Once the payment succeeds, the payment run updates the status of the subscription to active.
Merchandizer-initiated pause, resume, or cancellation​
  1. The merchandizer pauses, resumes, or cancels the subscription on the subscriber's behalf.
    • The subscription status is active.
    • paused or cancelled is set to true (for pause or cancel).
    • the paused_at or cancelled_at timestamp is populated with the date and time the subscription was 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 merchandizer resumes the subscription:
    • 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 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, 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.

Paying for an Order​

Elastic Path Payments Powered by Stripe supports three ways to pay for an order that contains a subscription.

The first way is a single purchase payment for the full order amount. The gateway attempts to take payment immediately and returns the result of the attempt. See Payment Requests for the purchase payment mechanism.

The second and third ways use a payment intent. A payment intent tracks a multi-step Stripe payment. You set up the payment intent on the cart before checkout. This supports payment methods that need more than one step, for example a bank transfer or a card that needs additional verification.

A payment intent uses one of two capture methods. With automatic capture, the gateway takes payment as soon as the payment intent completes. This behaves like a purchase payment. With manual capture, the gateway only authorizes the payment. You send a separate capture request to take the payment.

Elastic Path Subscriptions creates the subscription only when the order reaches the paid payment status. For automatic capture, this happens as soon as the payment intent completes. For manual capture, this happens only after the separate capture request completes. An order that is only authorized does not create a subscription.

When an order pays for a subscription through a payment intent, Subscriptions reads the payment method and customer from that payment intent. Subscriptions uses this payment method for future invoice payments. A subscriber can update the payment method later. See Card Declines.

Ask External AI