Marketcloud Javascript SDK

Introduction
Installation
Authentication and security
Promises
Sorting
Addresses
Brands
- Retrieve a brand
- List all brands
Categories
- Retrieve a category
- List all categories
Carts
Collections
- Retrieve a collection
- List all collections
Contents
- Retrieve a content
- List contents
Coupons
- Retrieve a coupon
- List coupons
Orders

Usage with orders

<ul dir="auto">
  <li>
    <a rel="nofollow noopener" target="_blank" href="#retrieve-a-payment-method">Retrieve a payment method</a>
  </li>
  <li>
    <a rel="nofollow noopener" target="_blank" href="#list-all-payment-methods">List all payment methods</a>
  </li>
</ul>

Payments
- Create a payment
Products
- Retrieve a product
- List all products
Promotions
Users
Variables
- Retrieve a variable
- List all variables

This is the documentation for the official Marketcloud Javascript SDK. It is a wrapper for our REST api and it makes it easier to use. This document provides an API reference for versions 2.0.0 and above of the SDK, we highly recommend to use the latest version of the SDK and before upgrading, please read the changelog.

Introduction

If you haven’t set up an application yet, please refer to the Getting Started section. You can also check out our API Reference for more detailed information about our SDK.
In Marketcloud, you create an App for each of your web/mobile applications. Each App has its own public key that you insert into your web app. Your account on Marketcloud can handle multiple Apps.

Installation

You can get the javascript SDK from Github:

git clone https://github.com/Marketcloud/marketcloud-js.git

Or you can use NPM:

npm install marketcloud-js

Or you can use bower:

bower install marketcloud-js

At this point you can include the minified javascript file in your application

<script type="text/javascript" src="https://github.com/Marketcloud/dist/marketcloud.min.js"></script>

Authentication and security

Every application identifies itself to Marketcloud using a unique public key. Since you must ship the public key with your client application code, this key is public. The application security is guaranteed by the secret key, which you should never share with anyone. The only place where it should be safe to store and use the secret key is (in case you need it) your server side code.

//Create a new instance of the client
  var marketcloud = new Marketcloud.Client({
    public_key : 'your-apps-public-key'
  })

Note
By default, the SDK will have very limited write and read access. Most write operations will require user authentication. If the default user authorizations are not enough for your application (for example if you are building a Marketplace) you can create new user roles. Learn more

Some methods requires a user authorization token. This is because, for example, only logged users should be able to edit their profile informations, or review their orders and items in carts. Whenever a method requires authentication, you will see a label.
In order to authenticate a user, use the users.authenticate() method.

Promises

Even if the examples in this reference use callbacks, starting with version 2.0.0 of the SDK, each endpoint method also returns a promise.

// This is ok
marketcloud.products.list({},function(err,response){
 console.log("My products:",response.data);
})

// Also this is ok
marketcloud.products.list({})
.then(function(response){
  console.log("My products:",response.data);
})
.catch(function(error){
  console.log("Something went wrong",error);
})

For using promises, the SDK needs Bluebird as a dependency. If you are installing this SDK with NPM or Bower, they will handle dependencies for you.

Sorting

Whenever you are requesting a list of resources, using a list(query,callback) method, you can pass sorting parameters to the query object:


client.products.list({
  sort_by : "name",
  sort_order : "ASC"
})

sort_by is the name of the attribute you want to use for sorting and sort_order can have two values, ASC or DESC.

Addresses

Create an address

Arguments

Field
Type
Description

full_name Required

String
The full name of the resident

email Required

String
A valid email address

country Required

String
The country of the address

state
String
The state of the address

city Required

String
The city of the address

address1 Required

String
The first address

address2
String
Additional address space

postal_code Required

String
The postal code of the address

phone_number
String
The phone number for the address

alternate_phone_number
String
An alternate phone number for the address

Example request


marketcloud.addresses.create(new_address,function(err,response){

})

List all addresses

Arguments

Field
Type
Description

user_id
Number
Filter addresses by the customer’s id.

fields
String
Comma separated list of attribute names to retrieve. Use it to retrieve only the fields you need.

per_page
Number
The number of addresses to retrieve per page

page
Number
The page number of addresses to display

Retrieves a list of addresses filtered and sorted by the query object.
Example request


marketcloud.addresses.list(query,function(err){
  // Your code here
})

Retrieve an address

Retrieves an address by its id.
Example request


marketcloud.addresses.getById(address_id,function(err,response){
  // Your code here
})

Update an address

Updates a address by id.
Arguments

Field
Type
Description

address_id Required

Number
The univocal address identifier

update_data Required

Object
An object containing the updates. See addresses.create() for more informations.

Example request


marketcloud.addresses.update(address_id,update_data,function(err,response){
  // Your code here
})

Delete an address

Deletes a address by id.
Example request


marketcloud.addresses.delete(address_id,function(err){
  // Your code here
})

Brands

Retrieve a brand

//Retrieves a brand by its id
  marketcloud.brands.getById(brand_id, function(err,response){

});

List all brands

Retrieves a list of Brands filtered and sorted by the query object.
Arguments

Field
Type
Description

fields
String
Comma separated list of attribute names to retrieve. Use it to retrieve only the fields you need.

per_page
Number
The number of brands to retrieve per page

page
Number
The page number of brands to display

Example request

//Retrieves a list of Brands filtered and sorted by the query object
marketcloud.brands.list(query, function(err,response){
});

Carts

Create a cart

Arguments

Field
Type
Description

items Required

Array of Objects
The list of items, in the form {product_id:1,quantity:10, [variant_id:1]}, added on the cart

A line item is an object with the following attributes

Field
Type
Description

product_id Required

Number
The univocal product identifier

variant_id
Number
The univocal number identifying a product’s variant.

quantity Required

Number
A positive number that indicates how many units of the chosen product must be added to cart.

Creates a new cart with a product in it.
Example request


  //Creates a new cart for the user with given email
  marketcloud.carts.create({
      items:[{'product_id':111,'quantity':1}]
  },function(err,response){

  });

Retrieve a cart

Example request


marketcloud.carts.getById(cart_id,function(err,response){
  // Your code here
})

Add items to cart


  //Add products to a cart identified by its id
  marketcloud.carts.add(cart_id,[{'product_id':5785,'quantity':2}],
  ,function(err,response){

  });

Update cart contents


  marketcloud.carts.update(testCart.id,[
                      {'product_id':5712,'quantity':1},
                      {'product_id':5785,'quantity':1}
      ],function(err,response){

  })

Add a coupon to the cart


  marketcloud.carts.addCoupon(testCart.id,"COUPON_CODE",function(err,response){

  })

Remove cart contents


  marketcloud.carts.remove(testCart.id,[
                      {'product_id':5712},
                      {'product_id':5785}
      ],function(err,response){
          //Assuming that the cart had only 2 products,
          //It should be empty now

      })

If your store works with variants, you need to explicitly indicate which variant you want to add/remove/update .


  //Adds an item to the cart
  marketcloud.carts.add(cart_id,[{'product_id':5785,'quantity':2, 'variant_id' : 3}],
  ,function(err,response){

  });

  //Updates an item in the cart
  marketcloud.carts.update(cart_id,[{'product_id':5785,'quantity':1, 'variant_id' : 3}],
  ,function(err,response){

  });

  //Remove an item from the cart
  marketcloud.carts.remove(cart_id,[{'product_id':5785, 'variant_id' : 3}],
  ,function(err,response){

  });

Collections

Retrieve a collection

Example request

//Retrieves a collection by its id
marketcloud.collections.getById(123)
.then(function(response){

})
.catch(function(error){

})

List all collections

Retrieves a list of Collections filtered and sorted by the query object.
Arguments

Field
Type
Description

fields
String
Comma separated list of attribute names to retrieve. Use it to retrieve only the fields you need.

per_page
Integer
The number of collections to retrieve per page

page
Integer
The page number of collections to display

Example request


marketcloud.collections.list({})
.then(function(response){

})
.catch(function(error){

})

Retrieve a content

//Retrieves a content by its id
  marketcloud.contents.getById(content_id, function(err,response){

});

List contents

//Retrieves a paginated list of categories filtered and sorted by the query object
  marketcloud.contents.list(query, function(err,response){
});

Coupons

Retrieve a coupon

Example request

//Retrieves a coupon by its id
marketcloud.coupons.getById(123);

List coupons

Example request

//Retrieves a paginated list of coupons
// in this example, we only look for active coupons
marketcloud.coupons.list({active : true});

Orders

List all orders


//Returns orders made by the currently authenticated user
marketcloud.orders.list(query,function(err,response){

})

Retrieve an order


  //Returns informations about an order made by the currently authenticated user
  marketcloud.orders.getById(id,function(err,response){
  });

Create an order

Arguments

Field
Type
Description

items
Array
An array of line items.This is required if the is missing.

cart_id Required

Integer
The id of the cart that is going to be turned into an order. This is required if is missing

state
String
The state of the order. Defaults to created

shipping_address_id Required

Integer
The id of the shipping address

shipping_address
Object
A shipping address object. See Address for more informations. This is required if the is missing.

billing_address_id Required

Integer
The id of the billing address

billing_address
Object
A sbilling address object. See Address for more informations. This is required if the is missing.

user_id
Integer
The id of the user making the order

shipping_id
Integer
The id of the shipping method chosen for the order. Be careful, this is not the shipping address.

store_id
Integer
The id of the store receiving in the order

promotion_id
Number
The id of the promotion to…

Marketcloud Javascript SDK

Introduction

Installation

Authentication and security

Promises

Sorting

Addresses

Create an address

List all addresses

Retrieve an address

Update an address

Delete an address

Brands

Retrieve a brand

List all brands

Categories

Retrieve a category

List all categories

Carts

Create a cart

Retrieve a cart

Add items to cart

Update cart contents

Add a coupon to the cart

Remove cart contents

Collections

Retrieve a collection

List all collections

Contents

Retrieve a content

List contents

Coupons

Retrieve a coupon

List coupons

Orders

List all orders

Retrieve an order

Create an order