Activating a Subscription

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}.vendhq.com/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.

Partner Consent MarshmallowPartner Consent Marshmallow

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.

ParameterDescription
retailer_idThe id of the retailer who just consented to subscribe to your app
subscription_idThe id of the subscription that was just created

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

Error CodeError MessageWhen
500000Token not providedDidn't provide a token when redirecting a retailer to the consent flow.
500001Token is usedThe token provided in the consent flow has already been used.
500002Token is expiredThe token provided in the consent flow has expired. (Tokens expire after 24 hours)
500003Token is invalidWe couldn't find the token you provided for the consent flow in our backend.
500004Retailer does not have a Lightspeed Retail (X-Series) subscriptionA retailer tried to activate the subscription but has an inactive Lightspeed Retail (X-Series) account.
500005Retailer does not have a Lightspeed Retail (X-Series) subscriptionA retailer tried to activate the subscription but did not have a Lightspeed Retail (X-Series) subscription.
500006Retailer does not have a paid Lightspeed Retail (X-Series) subscriptionA retailer tried to activate the subscription but is on a free Lightspeed Retail (X-Series) plan.
500007Retailer does not have a payment profile associated with their subscriptionA retailer tried to activate the subscription but did not have a payment method associated with their Lightspeed Retail (X-Series) account.
500008Retailer has an existing subscription for this partnerA retailer tried to activate the subscription but was already subscribed to a product by the same third party.
500009Product not found for currencyA retailer tried to activate a subscription but the product does not support the retailer's current billing currency.
500010Retailer rejected consentA retailer rejects activating a subscription.
500011Failed to create subscriptionWe failed to create the subscription on our side.
500012Retailer subscription is not activeA retailer tried to activate a subscription that is not active.
500100Product handle not foundThe desired product doesn't match anything in Lightspeed Retail (X-Series) side.
500101Product price point handle not found for currencyThe product is missing a price point entry in Lightspeed Retail (X-Series) for the desired currency.
500102Token string creation process failedAn unexpected failure occurred while trying to generate the URL token.
500103Token insertion to DB failedThe generated URL token couldn't be inserted into Lightspeed Retail (X-Series) database.
500104Component handle not foundThe desired component doesn't match anything in Lightspeed Retail (X-Series) side.
500105Component quantity must be positiveThe component quantity is not a positive number.
500106Component price point handle not foundThe component is missing a price point entry in Lightspeed Retail (X-Series).
500107Duplicate components in payloadSeveral of the same components are used in the payload.
500108Invalid coupon codeCoupon code is invalid when you create a new subscription token.
500109Product or price point must be different to the current subscriptionA retailer tries to update 3PB subscription but both product and price point are the same as current subscription.
500110Component quantity must be different to the current subscription's component quantityA retailer tries to change component subscription but the quantity is the same as current value.
500111Product price point is required if product handle is specifiedA retailer tries to change product but price point handle is not provided.
500112Retailer is not authorized to act on this PartnerSubscriptionTokenA retailer tries to call 3PB API with an invalid authorization token.
500113Updating product and components at the same time is not supported yetWhen updating a subscription a retailer can update either their plan or add/remove components, but not both.
500114Product handle and components are emptyThe retailer must supply either a product plan to update to, or components to add or remove.

Did this page help you?