Third Party Billing - activating a subscription

Introduction

Lightspeed Retail (X-Series) now supports adding apps to a retailer's existing billing profile. This makes life easier for our retailers, allowing them to consolidate their billing in one place. It also makes life easier for our integrators, as we handle all the complexities of billing on your behalf, allowing you to focus on developing a great integration.

If you'd use these APIs, please contact [email protected] and we can help get you onboard

Example Flow

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

1. Retailer authenticates with Lightspeed Retail (X-Series)

Before a retailer can subscribe to your app you should first get them to authenticate using our API. Please refer to our authorization documentation to see how to do this.

Connecting your application to a Lightspeed Retail (X-Series) Retailer Account

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 subscribe to your app

2.1 Get a token for new subscription

A retailer wants to use your app with Lightspeed Retail (X-Series). They reach a page on your website in order to activate a new subscription. For example, you may have an "Activate" button on your website. When they click "Activate", you should make an API (POST) call to /api/2.0/partner/billing/token to get a token. In the body of this request, you need to specify all the information required for a new subscription, including product_handle, price_handle, and components if you want any, and return_url which will be redirected to after retailer accepts the subscription successfully in step 3. You may also use a coupon by the coupon_code field to offer some discount to your retailer. Please refer to the spec of /api/2.0/partner/billing/token for more details.

This endpoint will return you a token representing your request to create a new 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 new subscription

Once 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 consent to adding your app 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 subscription

When a user consents to adding your app to their bill by clicking the "Accept" button in the page prompted in step 2.2, we will make a call to our backend and add your plan 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. We attach the following query parameters to this return_url to help you with any reconciliation you might want to do.

An example of the url will look something like this https://www.marshmallow.com/vend?retailer_id=123&subscription_id=123

These parameters can be used against our API to get information about the subscription you just created. For example, you can get the subscription data by subscription_id from /api/2.0/partner/billing/subscriptions/{subscription_id} endpoint. Please reference the Third Party Billing API Reference for a complete spec of all available APIs.

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 per new subscription you want to create.

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

Error Handling

In some cases we will redirect a retailer back to your return url with some error parameters. It is highly recommended that you handle these cases in the flow you implement.

This is an example of how the URL will look like:
https://{partner_return_url}?error={error}&error_message={error_message}

Example:
https://www.marshmallow.com/vend?error=500001&error_message=The%20token%20provided%20in%20the%20consent%20flow%20has%20already%20been%20used.

Error Code Mappings