Third Party Billing - updating an existing subscription

Example Flow - updating a third party billing subscription

This is the step by step flow a partner should follow when updating a third party billing subscription.

1. Retailer has existing third party billing subscription

Before a retailer can update their subscription to your app, they first need to have authenticated and created a third party billing subscription. Please refer to our documentation for creating a subscription here -
Creating a third party billing subscription

We will need the access_token generated from it for authorization in every API call in the following steps. Also, all API calls should be made against the retailer's domain as the base URL, for example, https://<<domain_prefix>>.retail.lightspeed.app/api/2.0/partner/billing/token

2. Retailer wants to update an existing subscription to your app

2.1 Get a token for updating a subscription

A retailer wants to update their existing subscription to your app with Lightspeed Retail (X-Series). They reach a page on your website in order to update their subscription. For example, you may have an "Update Subscription" button on your website. When they click "Update Subscription", you should make an API (POST) call to /api/2.0/partner/billing/update-subscription/token to get a token. In the body of this request, you need to specify all the information required to update a subscription. This includes either updating the plan (product_handle and price_handle) or updating the components (components), but not both at the same time. You'll also need to specify the return_url which they will be redirected to after retailer accepts the charges for the updated subscription in step 3. Please refer to the spec of /api/2.0/partner/billing/update-subscription/token for more details.

This endpoint will return you a token representing your request to update the subscription.

{
	"token": "0a7e36eb05a94bf1a4d3daeff0f561f9",
	"expires_in": "86400",
	"expires_at": "expires_at"
}

REMINDER: Don't forget to put your access_token in the HTTP header for authorization
Authorization: Bearer <your access_token>

2.2 Retailer confirms the updates to their existing subscription

Once you successfully get the token in step 2.1, you should then use this token to redirect the user to /billing/partner-consent?token={token}

This page will prompt the user to accept the new changes that will be charged to their Lightspeed Retail (X-Series) bill. For the marshmallow product this looks like the image below.

NOTE: This is an HTTP REDIRECT instead of an API call

3. Retailer accepts updates to subscription

When a user accepts the new charges to their bill by clicking the "Update Subscription" button in the page prompted in step 2.2, we will make a call to our backend and make the necessary updates to their bill.

Once this has successfully completed we will redirect the user to the return_url you provided when you generated your token in the step 2.1.

Once this flow has been completed the token you generated in step 2.1 will be invalidated and cannot be used again.

You will hence have to generate a token for every update that you want to make to a subscription.

It is also important to note that tokens expire after 24 hours.

Error Handling

Error handling for this flow can be found in the previous tutorial when creating a subscription - Creating a third party billing subscription