Third Party Billing - Partner Tutorial

Introduction

Vend supports adding apps to a customer’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, we’ll handle all the complexities of billing on your behalf, allowing you to focus on developing a primo integration.

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

2. Retailer wants to subscribe to your app

A retailer wants to use your app with Vend. They reach a page on your website that looks something like the image below.

When they click activate you should make an API (POST) call to /api/2.0/partner/billing to get a token.

This endpoint will return you a token.

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

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.

3. Retailer accepts subscription

When a user consents to adding your app to their bill 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 previous step.

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 created

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. Please reference the [Third Party Billing API Reference]() for more information.

Once this flow has been completed the token you generated 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.