API for E-commerce Partners. This document includes Cart, Discount, Payment, Order and Return related endpoints provided by Global Miles.
The generated SDK relies on Node Package Manager (NPM) being available to resolve dependencies. If you don't already have NPM installed, please go ahead and follow instructions to install NPM from here. The SDK also requires Node to be installed. If Node isn't already installed, please install it from here
NPM is installed by default when Node is installed
To check if node and npm have been successfully installed, write the following commands in command prompt:
node --version
npm -version
Now use npm to resolve all dependencies by running the following command in the root directory (of the SDK folder):
npm install
This will install all dependencies in the node_modules
folder.
Once dependencies are resolved, you will need to move the folder GlobalMilesECommerceAPILib
in to your node_modules
folder.
The following section explains how to use the library in a new project.
Open an IDE/Text Editor for JavaScript like Sublime Text. The basic workflow presented here is also applicable if you prefer using a different editor or IDE.
Click on File
and select Open Folder
.
Select the folder of your SDK and click on Select Folder
to open it up in Sublime Text. The folder will become visible in the bar on the left.
Now right click on the folder name and select the New File
option to create a new test file. Save it as index.js
Now import the generated NodeJS library using the following lines of code:
var lib = require('lib');
Save changes.
To run the index.js
file, open up the command prompt and navigate to the Path where the SDK folder resides. Type the following command to run the file:
node index.js
These tests use Mocha framework for testing, coupled with Chai for assertions. These dependencies need to be installed for tests to run. Tests can be run in a number of ways:
- Navigate to the root directory of the SDK folder from command prompt.
- Type
mocha --recursive
to run all the tests.
- Navigate to the
../test/Controllers/
directory from command prompt. - Type
mocha *
to run all the tests.
- Navigate to the
../test/Controllers/
directory from command prompt. - Type
mocha Global Miles E-commerce APIController
to run all the tests in that controller file.
To increase mocha's default timeout, you can change the
TEST_TIMEOUT
parameter's value inTestBootstrap.js
.
In order to setup authentication in the API client, you need the following information.
Parameter | Description |
---|---|
oAuthClientId | OAuth 2 Client ID |
oAuthClientSecret | OAuth 2 Client Secret |
API client can be initialized as following:
const lib = require('lib');
// Configuration parameters and credentials
lib.Configuration.oAuthClientId = "oAuthClientId"; // OAuth 2 Client ID
lib.Configuration.oAuthClientSecret = "oAuthClientSecret"; // OAuth 2 Client Secret
You must now authorize the client.
This SDK uses OAuth 2.0 authorization to authorize the client.
The authorize()
method will exchange the OAuth client credentials for an access token.
The access token is an object containing information for authorizing client requests.
const tokenPromise = oAuthManager.authorize();
The Node.js SDK supports both callbacks and promises. So, the authorize call returns a promise and also returns response back in the callback (if one is provided)
The client can now make authorized endpoint calls.
It is recommended that you store the access token for reuse.
This code snippet stores the access token in a data store. For this example, node-localstorage is being used as the data store.
const lib = require('lib');
const LocalStorage = require('node-localstorage').LocalStorage;
const localStorage = new LocalStorage('./scratch');
localStorage.setItem('token', lib.Configuration.oAuthToken);
To authorize a client from a stored access token, just set the access token in Configuration
along with the other configuration parameters before making endpoint calls:
// load token later...
const lib = require('lib');
const LocalStorage = require('node-localstorage').LocalStorage;
const localStorage = new LocalStorage('./scratch');
lib.Configuration.oAuthToken = localStorage.getItem('token');
In this example, app.js
will check if the access token has been set in the SDK. If it has been, API calls can be made. Otherwise, client has to be authorized first before making API calls.
This example makes use of node-localstorage for handling data persistence.
const lib = require('lib');
const oAuthManager = lib.OAuthManager;
lib.Configuration.oAuthClientId = 'oAuthClientId'; // OAuth 2 Client ID
lib.Configuration.oAuthClientSecret = 'oAuthClientSecret'; // OAuth 2 Client Secret
// this method will be called whenever the token updates
// you can update the storage you're using with the updated token
lib.Configuration.oAuthTokenUpdateCallback = (token) => {
// token is the updated access_token
};
if (oAuthManager.isTokenSet()) {
// token is already stored in the client
// make API calls as required
} else {
const scopes = [];
const promise = oAuthManager.authorize(scopes);
promise.then((success) => {
// client authorized. API calls can be made
}, (exception) => {
// error occurred, `exception` will be of type lib/Exceptions/OAuthProviderException
});
}
The singleton instance of the EarnMilesController
class can be accessed from the API Client.
var controller = lib.EarnMilesController;
This endpoint allows to get list of orders. In order to get detailed order history and reconciliation you can use this endpoint.
You can try this API with configuring client parameters in Console Tab below. Test OAuthClientId is b30359c21700fd6f2b91154adcb7b37bab3e7e0a33e22682e5dd149d7a6ac4df and OAuthClientSecret is 4bc4335faad41d6a23cd059e495005f00496a64e34e6187b1d72695a8debd28c
function listOrders(filterStoreCode, filterCompletedAt, filterStatus, sort, callback)
Parameter | Tags | Description |
---|---|---|
filterStoreCode | Required |
Filter for an online store. |
filterCompletedAt | Required |
Filter for completed_at field. It is accepted a valid date range value. The format is YYYY-MM-DD..YYYY-MM-DD. |
filterStatus | Optional |
Filter for status field. It is accepted a valid status value of order. |
sort | Optional |
Sort for some selected fields. In order to sort descending "-" value will be used before the field. Valid field values are "completed_at", "created_at", "updated_at", "status". |
var filterStoreCode = filter[store_code];
var filterCompletedAt = filter[completed_at];
var filterStatus = filter[status];
var sort = 'sort';
controller.listOrders(filterStoreCode, filterCompletedAt, filterStatus, sort, function(error, response, context) {
});
This endpoint allows to create an order for earn miles. It may also include discounts and payments.
You can try this API with configuring client parameters in Console Tab below. Test OAuthClientId is b30359c21700fd6f2b91154adcb7b37bab3e7e0a33e22682e5dd149d7a6ac4df and OAuthClientSecret is 4bc4335faad41d6a23cd059e495005f00496a64e34e6187b1d72695a8debd28c
function createOrder(body, callback)
Parameter | Tags | Description |
---|---|---|
body | Required |
The body of the request. |
var body = new OrderRequest({"key":"value"});
controller.createOrder(body, function(error, response, context) {
});
This endpoint allows to get an order.
You can try this API with configuring client parameters in Console Tab below. Test OAuthClientId is b30359c21700fd6f2b91154adcb7b37bab3e7e0a33e22682e5dd149d7a6ac4df and OAuthClientSecret is 4bc4335faad41d6a23cd059e495005f00496a64e34e6187b1d72695a8debd28c
function retrieveOrder(transactionId, callback)
Parameter | Tags | Description |
---|---|---|
transactionId | Required |
The ID of the transaction that represents the order. |
var transactionId = transaction_id;
controller.retrieveOrder(transactionId, function(error, response, context) {
});
This endpoint allows to get available amount of money, based on miles of user and their discounts which is based on cart or items.
You can try this API with configuring client parameters in Console Tab below. Test OAuthClientId is b30359c21700fd6f2b91154adcb7b37bab3e7e0a33e22682e5dd149d7a6ac4df and OAuthClientSecret is 4bc4335faad41d6a23cd059e495005f00496a64e34e6187b1d72695a8debd28c
function createCart(body, callback)
Parameter | Tags | Description |
---|---|---|
body | Required |
The body of the request. |
var body = new CartRequest({"key":"value"});
controller.createCart(body, function(error, response, context) {
});
The singleton instance of the AuthenticationController
class can be accessed from the API Client.
var controller = lib.AuthenticationController;
Tags:
Skips Authentication
An access token will allow you to make requests for the system. We support only one type of token: client_credentials.
You can try this API with configuring client parameters in Console Tab below. Test OAuthClientId is b30359c21700fd6f2b91154adcb7b37bab3e7e0a33e22682e5dd149d7a6ac4df and OAuthClientSecret is 4bc4335faad41d6a23cd059e495005f00496a64e34e6187b1d72695a8debd28c
function createAuthentication(accept, contentType, body, callback)
Parameter | Tags | Description |
---|---|---|
accept | Required DefaultValue |
It advertises which content type is able to understand. |
contentType | Required DefaultValue |
It tells the client what the content type of the returned. |
body | Required |
The body of the request. |
var accept = 'application/json';
var contentType = 'application/json';
var body = new OAuthRequest({
"client_id": "{{client_id}}",
"client_secret": "{{client_secret}}",
"grant_type": "{{grant_type}}"
});
controller.createAuthentication(accept, contentType, body, function(error, response, context) {
});
The singleton instance of the ReturnController
class can be accessed from the API Client.
var controller = lib.ReturnController;
This endpoint allows to get a return.
You can try this API with configuring client parameters in Console Tab below. Test OAuthClientId is b30359c21700fd6f2b91154adcb7b37bab3e7e0a33e22682e5dd149d7a6ac4df and OAuthClientSecret is 4bc4335faad41d6a23cd059e495005f00496a64e34e6187b1d72695a8debd28c
function retrieveReturn(returnProvisionToken, callback)
Parameter | Tags | Description |
---|---|---|
returnProvisionToken | Required |
The token value of a return. |
var returnProvisionToken = return_provision_token;
controller.retrieveReturn(returnProvisionToken, function(error, response, context) {
});
This endpoint allows to cancel a return.
You can try this API with configuring client parameters in Console Tab below. Test OAuthClientId is b30359c21700fd6f2b91154adcb7b37bab3e7e0a33e22682e5dd149d7a6ac4df and OAuthClientSecret is 4bc4335faad41d6a23cd059e495005f00496a64e34e6187b1d72695a8debd28c
function deleteCancelReturn(body, callback)
Parameter | Tags | Description |
---|---|---|
body | Required |
The body of the request. |
var body = new CancelReturnRequest({"key":"value"});
controller.deleteCancelReturn(body, function(error, response, context) {
});
This endpoint allows to complete a return.
You can try this API with configuring client parameters in Console Tab below. Test OAuthClientId is b30359c21700fd6f2b91154adcb7b37bab3e7e0a33e22682e5dd149d7a6ac4df and OAuthClientSecret is 4bc4335faad41d6a23cd059e495005f00496a64e34e6187b1d72695a8debd28c
function updateCompleteReturn(body, callback)
Parameter | Tags | Description |
---|---|---|
body | Required |
The body of the request. |
var body = new CompleteReturnRequest({"key":"value"});
controller.updateCompleteReturn(body, function(error, response, context) {
});
This endpoint allows to start a return for a specific order.
You can try this API with configuring client parameters in Console Tab below. Test OAuthClientId is b30359c21700fd6f2b91154adcb7b37bab3e7e0a33e22682e5dd149d7a6ac4df and OAuthClientSecret is 4bc4335faad41d6a23cd059e495005f00496a64e34e6187b1d72695a8debd28c
function createStartReturn(body, callback)
Parameter | Tags | Description |
---|---|---|
body | Required |
The body of the request. |
var body = new StartReturnRequest({"key":"value"});
controller.createStartReturn(body, function(error, response, context) {
});
This endpoint allows to get list of returns. In order to get detailed return history and reconciliation you can use this endpoint.
You can try this API with configuring client parameters in Console Tab below. Test OAuthClientId is b30359c21700fd6f2b91154adcb7b37bab3e7e0a33e22682e5dd149d7a6ac4df and OAuthClientSecret is 4bc4335faad41d6a23cd059e495005f00496a64e34e6187b1d72695a8debd28c
function listReturns(filterStoreCode, filterCreatedAt, filterStatus, sort, callback)
Parameter | Tags | Description |
---|---|---|
filterStoreCode | Required |
Filter for an online store. |
filterCreatedAt | Required |
Filter for created_at field. It is accepted a valid date range value. The format is YYYY-MM-DD..YYYY-MM-DD. |
filterStatus | Optional |
Filter for status field. It is accepted a valid status value of return. |
sort | Optional |
Sort for some selected fields. In order to sort descending "-" value will be used before the field. Valid field values are "created_at", "updated_at", "status". |
var filterStoreCode = filter[store_code];
var filterCreatedAt = filter[created_at];
var filterStatus = filter[status];
var sort = 'sort';
controller.listReturns(filterStoreCode, filterCreatedAt, filterStatus, sort, function(error, response, context) {
});
The singleton instance of the PayWithMilesController
class can be accessed from the API Client.
var controller = lib.PayWithMilesController;
This endpoint allows to get list of payments. In order to get detailed payment history and reconciliation you can use this endpoint.
You can try this API with configuring client parameters in Console Tab below. Test OAuthClientId is b30359c21700fd6f2b91154adcb7b37bab3e7e0a33e22682e5dd149d7a6ac4df and OAuthClientSecret is 4bc4335faad41d6a23cd059e495005f00496a64e34e6187b1d72695a8debd28c
function listMilePayments(filterStoreCode, filterCreatedAt, filterStatus, sort, callback)
Parameter | Tags | Description |
---|---|---|
filterStoreCode | Required |
Filter for an online store. |
filterCreatedAt | Required |
Filter for created_at field. It is accepted a valid date range value. The format is YYYY-MM-DD..YYYY-MM-DD. |
filterStatus | Optional |
Filter for status field. It is accepted a valid status value of payment. |
sort | Optional |
Sort for some selected fields. In order to sort descending "-" value will be used before the field. Valid field values are "created_at", "updated_at", "status". |
var filterStoreCode = filter[store_code];
var filterCreatedAt = filter[created_at];
var filterStatus = filter[status];
var sort = 'sort';
controller.listMilePayments(filterStoreCode, filterCreatedAt, filterStatus, sort, function(error, response, context) {
});
After successful authentication and retrieving needed token, this endpoint allows to start a payment transaction. To be able to complete whole payment process successfully also check "Complete Mile Payment endpoint" please.
You can try this API with configuring client parameters in Console Tab below. Test OAuthClientId is b30359c21700fd6f2b91154adcb7b37bab3e7e0a33e22682e5dd149d7a6ac4df and OAuthClientSecret is 4bc4335faad41d6a23cd059e495005f00496a64e34e6187b1d72695a8debd28c
function createStartMilePayment(body, callback)
Parameter | Tags | Description |
---|---|---|
body | Required |
The body of the request. |
var body = new StartMilePaymentRequest({"key":"value"});
controller.createStartMilePayment(body, function(error, response, context) {
});
This endpoint allows to complete a payment.
You can try this API with configuring client parameters in Console Tab below. Test OAuthClientId is b30359c21700fd6f2b91154adcb7b37bab3e7e0a33e22682e5dd149d7a6ac4df and OAuthClientSecret is 4bc4335faad41d6a23cd059e495005f00496a64e34e6187b1d72695a8debd28c
function updateCompleteMilePayment(body, callback)
Parameter | Tags | Description |
---|---|---|
body | Required |
The body of the request. |
var body = new CompleteMilePaymentRequest({"key":"value"});
controller.updateCompleteMilePayment(body, function(error, response, context) {
});
This endpoint allows to cancel a payment.
You can try this API with configuring client parameters in Console Tab below. Test OAuthClientId is b30359c21700fd6f2b91154adcb7b37bab3e7e0a33e22682e5dd149d7a6ac4df and OAuthClientSecret is 4bc4335faad41d6a23cd059e495005f00496a64e34e6187b1d72695a8debd28c
function deleteCancelMilePayment(body, callback)
Parameter | Tags | Description |
---|---|---|
body | Required |
The body of the request. |
var body = new CancelMilePaymentRequest({"key":"value"});
controller.deleteCancelMilePayment(body, function(error, response, context) {
});
This endpoint allows to refund a payment.
You can try this API with configuring client parameters in Console Tab below. Test OAuthClientId is b30359c21700fd6f2b91154adcb7b37bab3e7e0a33e22682e5dd149d7a6ac4df and OAuthClientSecret is 4bc4335faad41d6a23cd059e495005f00496a64e34e6187b1d72695a8debd28c
function createRefundMilePayment(body, callback)
Parameter | Tags | Description |
---|---|---|
body | Required |
The body of the request. |
var body = new RefundMilePaymentRequest({"key":"value"});
controller.createRefundMilePayment(body, function(error, response, context) {
});