Subscriptions and memberships

How to sell a subscription or a membership, show it in an account page, and let the customer cancel, upgrade and renew it.

This guide describes the requests a storefront makes to sell subscriptions and memberships and to let a signed-in customer manage them.

Terms

Term	Meaning
Subscription product	A product in a catalogue that has a feature of the type `Subscription`. The feature holds the billing schedule, the price, an optional trial and the permitted upgrades.
Subscription	The record that OneBasket creates when a contact buys a subscription product and the order is processed. It holds the status and the billing dates.
Membership	A subscription product that an organisation sells as a membership. The API has no separate membership resource. A membership is bought, listed, cancelled, upgraded and renewed as a subscription.
Entitlement	A benefit that a subscription gives to the customer, such as access to video content or to a ticket sale. OneBasket grants entitlements when the subscription starts and removes them when it ends.

A subscription has one of three billing schedules:

`billingSchedule.type`	Behaviour
`recurring`	Renews automatically at the end of every period, for example every month. OneBasket charges the saved payment method.
`fixed-term`	Runs between two fixed dates, for example one season. It does not renew automatically. The customer renews it by buying a product for the next term.
`manual`	OneBasket does not bill it on a schedule.

Every request in this guide except the product search needs the API key and a bearer token. A subscription always belongs to a contact, so the customer must be signed in before checkout.

Sell a subscription or membership

Find the subscription products

Call Get products with subscriptionsOnly=true.

In each product variant, find the feature with type equal to Subscription. Keep its key. This is the subscription key. The feature also contains the billing schedule, the price and the trial to show to the customer.

Add the product to a basket

Call Add product to basket with the id of the variant as productVariantId and the subscription key as subscriptionKey.

{
  "quantity": 1,
  "productVariantId": "<variant id>",
  "subscriptionKey": "<key of the Subscription feature>",
  "currency": "GBP"
}

Check out

Follow the Checkout flow. Send the bearer token, so that the basket belongs to the contact.

Wait for the subscription

OneBasket creates the subscription and grants its entitlements after the order is processed. This is asynchronous. After checkout, call List subscriptions or List entitlements until the new subscription or entitlement is returned.

Show the subscriptions of a customer

Call List subscriptions. The response contains every subscription of the contact, including ones that have ended.

Property	Use it to
`status`	Decide whether the subscription is in use. `Trial` and `Active` are in use. `Cancelled` is in use until `state.activeUntil`.
`state`	Show the date that matters for the status: `nextBillingDate`, `trialEndDate` or `activeUntil`.
`billingSchedule`	Show how the subscription is billed and whether the customer is allowed to cancel it (`isUserCancellable`).
`canManage`	Hide the cancel, upgrade and payment method actions when it is `false`. The contact then only receives the benefits of a subscription that another contact pays for.
`isExternallyManaged`	Hide the same actions when it is `true`. The subscription is then billed by a system outside OneBasket, such as a mobile app store, and the customer manages it there.

Check what a customer has access to

Call List entitlements. Compare the entitlementId values with the entitlement ids of your store. Use entitlements, not the name of a subscription, to decide what a customer is allowed to see or do. Several products can give the same entitlement.

Cancel a subscription

Check that billingSchedule.isUserCancellable and canManage are both true.
Call Cancel a subscription.
Call List subscriptions again. The status is Cancelled and state.activeUntil is the date until which the customer keeps the benefits.

To reverse the request, call Withdraw a cancellation.

Upgrade a subscription

An upgrade replaces the current subscription with a subscription to a different product, for example a higher membership tier.

Call Get upgrade targets with the id of the current subscription. Only offer the products that it returns.
Call Add product to basket with the productId of the chosen target in the path, and this body:

{
  "quantity": 1,
  "productVariantId": "<variantId of the upgrade target>",
  "subscriptionKey": "<subscriptionKey of the upgrade target>",
  "subscriptionUpgradeId": "<id of the current subscription>",
  "currency": "GBP"
}

Check out the basket.

Send subscriptionUpgradeId whenever the customer already holds a subscription that the new product replaces. Without it, OneBasket treats the request as a new purchase, and rejects it when the new product is not compatible with a product the customer already holds.

Renew a fixed-term subscription

Call Get renewal options. The response has one renewal group for each active fixed-term subscription of the contact.
When existingBasket is set, the contact already has a basket that contains the renewal. Continue with that basket.
When currentSubscription.status.isLocked is true, do not offer renewal. A renewal or a cancellation is already in progress.
Otherwise show options. Select the option with isSuggestedDefault by default. Show renewalDeadline when it is set.
Call Add product to basket with the productId of the chosen option in the path, and this body:

{
  "quantity": 1,
  "productVariantId": "<variantId of the option>",
  "subscriptionKey": "<subscriptionKey of the option>",
  "subscriptionRenewId": "<currentSubscription.subscriptionId>",
  "currency": "GBP"
}

Check out the basket.

Change the payment method

Renewals of a recurring subscription are charged to a saved payment method. To replace it:

Let the customer authorise a new payment method with the payment provider API of the store. The payment provider API returns a signed payment method id for the new payment method.
Call Update the payment method with that value as signedPaymentMethodId. To change several subscriptions in one request, call Update the payment method of several subscriptions and check updated on every result.

OneBasket rejects a signed payment method id that it did not issue, or that belongs to a different contact.

Subscriptions and memberships

On this page