Third Party Billing - Partner Tutorial

Introduction

Vend 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 partner-api@vendhq.com 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 Vend

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 Vend 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 Vend. 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 vend bill. For the marshmallow product this looks like the image below.

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

Parameter Description
retailer_id The id of the retailer who just consented to subscribe to your app
subscription_id The 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 Code Error Message When
500000 Token not provided Didn’t provide a token when redirecting a retailer to the consent flow.
500001 Token is used The token provided in the consent flow has already been used.
500002 Token is expired The token provided in the consent flow has expired. (Tokens expire after 24 hours)
500003 Token is invalid We couldn’t find the token you provided for the consent flow in our backend.
500004 Retailer does not have a Vend subscription A retailer tried to activate the subscription but has an inactive Vend account.
500005 Retailer does not have a Vend subscription A retailer tried to activate the subscription but did not have a Vend subscription.
500006 Retailer does not have a paid Vend subscription A retailer tried to activate the subscription but is on a free Vend plan.
500007 Retailer does not have a payment profile associated with their subscription A retailer tried to activate the subscription but did not have a payment method associated with their vend account.
500008 Retailer has an existing subscription for this partner A retailer tried to activate the subscription but was already subscribed to a product by the same third party.
500009 Product not found for currency A retailer tried to activate a subscription but the product does not support the retailer’s current billing currency.
500010 Retailer rejected consent A retailer rejects activating a subscription.
500011 Failed to create subscription We failed to create the subscription on our side.
500012 Retailer subscription is not active A retailer tried to activate a subscription that is not active.
500100 Product handle not found The desired product doesn’t match anything in Vend side.
500101 Product price point handle not found for currency The product is missing a price point entry in Vend for the desired currency.
500102 Token string creation process failed An unexpected failure occurred while trying to generate the URL token.
500103 Token insertion to DB failed The generated URL token couldn’t be inserted into Vend database.
500104 Component handle not found The desired component doesn’t match anything in Vend side.
500105 Component quantity must be positive The component quantity is not a positive number.
500106 Component price point handle not found The component is missing a price point entry in Vend.
500107 Duplicate components in payload Several of the same components are used in the payload.