Get Started

The Vendloop API is organized around REST. Our API has predictable resource-oriented URLs, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

The Vendloop API doesn’t support bulk updates. You can work on only one object per request.

What is a REST API?

API is short for ‘Application Programming Interface’ . An API is a set of rules that lets programs talk to each other, exposing data and functionality across the Internet in a consistent format.

REST stands for ‘Representational State Transfer’. This is an architectural pattern that describes how distributed systems can expose a consistent interface. When people use the term ‘REST API’, they are generally referring to an API accessed using the HTTP protocol at a predefined set of URLs.

These URLs represent various resources — any information or content accessed at that location, which can be returned as JSON, HTML, audio files, or images. Often resources have one or more methods that can be performed on them over HTTP, like GET, POST, PUT, and DELETE. The action represented by the first and last of these is clear, but POST and PUT have specific meanings. How they are defined is confusing, but the general rule is: use POST to create resources, and PUT to update resources.

https://api.vendloop.com/

Client Libraries

$ composer require vendloop/vendloop-php

Authentication

The Vendloop API uses API keys to authenticate requests. Include this key in the Authorization header of every request you make. You can view and manage your API keys in the Vendloop Dashboard.

Authorization headers should be in the following format: Authorization: Bearer SECRET_KEY

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Treat your API key like a password. Keep it safe and never share it with apps or people you don’t trust.

Use your API key by setting it in the initial configuration of new \Vendloop\VendloopClient(). The PHP library will then automatically send this key in each request.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

curl -L 'https://api.vendloop.com/' \
-H 'Authorization: Bearer SECRET_KEY'

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.vendloop.com/',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer SECRET_KEY'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

var myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer SECRET_KEY");

var requestOptions = {
  method: 'GET',
  headers: myHeaders,
  redirect: 'follow'
};

fetch("https://api.vendloop.com/", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

val client = OkHttpClient()
val request = Request.Builder()
  .url("https://api.vendloop.com/")
  .addHeader("Authorization", "Bearer SECRET_KEY")
  .build()
val response = client.newCall(request).execute()

Date & Time Formats

All dates and times are in UTC. In requests you should specify dates and times in UTC. When processing responses you should convert dates and times to your local time

YYYY-MM-DD HH:MM:SS

Rate Limits

The Vendloop API applies rate limits to the requests that it receives as a safeguards against bursts of incoming traffic to help maximize its stability. There might also be other additional resource-based rate limits. Your app should be prepared to handle this resource throttling.
A basic technique for integrations to gracefully handle limiting is to watch for 429 status codes and build in a retry mechanism. The retry mechanism should follow an exponential backoff schedule to reduce request volume when necessary.

The global rate limit is 300 requests per five minutes. If you exceed this, all API calls for the next five minutes will be blocked, receiving a HTTP 429 response.

Requests and Response

Both request body data and response data are formatted as JSON. Content type for responses will always be application/json.

status `boolean`	This lets you know if your request was succesful or not. We recommend that you use this in combination with HTTP status codes to determine the result of an API call.
message `string`	This is a summary of the response and its status. For instance when trying to retrieve a list of customers, message might read “Customers retrieved”. In the event of an error, the message key will contain a description of the error as with the authorization header situation above. This is the only key that is universal across requests.
data `object`	This contain the results of your request. It can either be an object, or an array depending on the request made. For instance, a request to retrieve a single customer will return a customer object in the data key, while the key would be an array of customers if a list is requested instead.

Errors

Vendloop API uses conventional HTTP response codes to indicate the success or failure of a request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, an operation failed, etc.). Codes in the 5xx range indicate an error with Vendloop’s servers

200 – OK	Everything worked as expected.
400 – Bad Request	The request was unacceptable, often due to missing a required parameter.
401 – Unauthorized	No valid API key provided was provided in the authorization header.
402 – Request Failed	The parameters were valid but the request failed.
403 – Forbidden	The API key doesn’t have permissions to perform the request.
404 – Not Found	The requested resource doesn’t exist.
429 – Too Many Requests	Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504 – Server Errors	Something went wrong on Vendloop’s end. This shouldn’t happen so please report as soon as you encounter any instance of this.

Testing

To test and explore the Vendloop API you can use Postman. Postman is a powerful and easy to use API development and testing platform.

Download and install Postman.
Get the Vendloop API Postman Collection and import it into Postman.
Define variables used in the postman collection. You should define base_url variable as https://api.vendloop.com and your Vendloop API Key as the secret_key variable. It is useful to configure variables in postman environments so you will not have to redefine the values for each request manually. Learn more about Postman environments