Cart Migration Documentation

To get vend API, first, you need to create a Vend application. To do this, follow the steps below:

1. Register as a developer

If you have not done this yet, register a developer account here.

NOTE: Your developer account credentials are independent of your Vend account so your existing Vend credentials will not work here.

2. Create a Vend application

Once you sign in you will be redirected to the list of your Applications. Now you are ready to create your first app. As a result, this process will give you the client_id and the client_secret which are used to identify your applications and are, therefore, required to complete the authorization process.

NOTE: redirect_uri is the address of your server which will accept the callback request from Vend. NOTE: You will notice that a newly created app is marked as Not Approved.

Don’t worry! You can still use this app. Not Approved just means that you can only connect your application to 30 Vend stores.

This should be more than enough for private apps or testing/staging environments. You only need to get our approval for production-ready, public applications. After that, let’s implement the following steps to connect your application to a Vend Retailer account:

3. Requesting authorization code

The Retailer (resource owner) needs to authorize your application to access their data. Send them to the following URL so that they can authorize your application.

https://secure.vendhq.com/connect?response_type=code&client_id={client_id}&redirect_uri={redirect_uri}&state={state}

NOTE: The redirect_uri must be the same as what is registered for the app in your developer dashboard. Once the Retailer has authorized the application, Vend will send an authorization code and the Retailer’s domain prefix to the Redirect URI you set up with your application.

• Successful authorization response:

{redirect_uri}?code={code}&domain_prefix={domain_prefix}&state={state}

• Decline access response:

{redirect_uri}?error=access_denied 

NOTE: The state parameter can be used to pass some arbitrary data, allowing you to bind the callback with a particular authorization request.

NOTE: The redirect_uri parameter should be defined exactly as it was when creating your application, without any additional parameters. NOTE: Currently, the Vend API does not support scopes.

4. Requesting an access token

Once you have the authorization code, your application can now request an access token and a refresh token.

The following data should be sent as “application/x-www-form-urlencoded” encoded body of a POST request.

NOTE: This data should not be sent as GET parameters in a query string.

• URL: https://{domain_prefix}.vendhq.com/api/1.0/token

• Parameters:

• code
• client_id
• client_secret
• grant_type – this is always authorization_code
• redirect_uri

NOTE: The code is a short-lived (10 minutes), single-use value. Based on that assumption, every new authorization request should start with Step 1.

• Response:

{
    "access_token": "fMYgxHEYtcyT8cvtvgi1Za5DRs4vArSyvydlnd9f",
    "token_type": "Bearer",
    "expires": 1387145621,
    "expires_in": 86400,
    "refresh_token": "J3F62YPIQdfJjJia1xJuaHp7NoQYtm9y0WadNBTh"
}

NOTE: The expires value is an absolute timestamp in seconds since the Unix epoch time (1970-01-01T00:00:00Z). NOTE: The value expires_in is a relative time duration in seconds since this response was created. Currently, tokens expire in 24hrs.

5. Using the token to access the Vend API

Your application can use the received access token to interact with the Vend API on behalf of the Retailer by providing the access token in an Authorization header. GET https://someprefix.vendhq.com/api/products/{id} Authorization: Bearer fMYgxHEYtcyT8cvtvgi1Za5DRs4vArSyvydlnd9f

6. Refreshing the access token

When the access token expires, your application can request a new access token using the refresh token received in Step 2.

• URL: https://someprefix.vendhq.com/api/1.0/token

• Parameters:
  • refresh_token
  • client_id
  • client_secret
  • grant_type – when refreshing tokens it should be refresh_token
• Response:

  {
   "access_token": "KD7gspXvfAmOsspC65YDqqJQ6FcAYbRROc4zPIMZ",
   "token_type": "Bearer",
   "expires": 1387145621,
   "expires_in": 604800
  }

NOTE: The response payload may include a refresh token. If so, you need to update your currently stored refresh token. If no refresh token exists in the payload, you can assume the refresh token was not rotated, and you can continue to use the original refresh token.