By using this website you implicitly accept our cookies. For more informations read our Cookie policy

Index

NodeJS SDK documentation

This is the documentation for the official Marketcloud NodeJS SDK. It is a wrapper for our REST api and it makes it easier to use. You can find the list of our official SDKs in the libraries section.

Introduction

If you haven't set up an application yet, please refer to this Getting Started guide.

Your account on Marketcloud can handle multiple marketcloud-apps, each one has its own public key / secret key pair that you insert into your NodeJS code.

The Marketcloud NodeJS SDK is open source and publicly available at Github

Installation

The easiest way to get started with the NodeJS sdk, is to install it via NPM:

npm install marketcloud-node

At this point you can include the sdk in your application

var Marketcloud = require('marketcloud-node');

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, since it grants higher authorization levels to clients using it. 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 or, even better, some safer place.

Your app's credentials are stored by the Marketcloud.Client instance

var marketcloud = new Marketcloud.Client({
        public_key : 'your_public_key',
        secret_key : 'your_secret_key'
    })

The token is transparently handled by the client and it lasts 4 hours, after that ,the SDK automatically detects the need to re-authenticate so you don't need to check for this.

Making requests

The SDK uses Promises to handle concurrency and to interact with the Marketcloud REST api. Promises provide a way to write asynchronous code that is readable and easily composable. The SDK internally uses the well known library Bluebird.js


marketcloud.products.list({})
.then(function(data){
  // Handle success
})
.catch(function(error){
  //Handle error
})
    
Handling errors

Errors returned by the SDK have the following structure


{
  code : 404,
  type : "NotFound",
  message : "Resource not found"
}
    

Validation error have further attributes:


{ code: 400,
  type: "BadRequest",
  message: "Bad request",
  valid: false,
  failedValidator: "missingRequiredProperty",
  invalidPropertyName: "price"
}
    

Handling currencies

Handling currencies in a multi-currencies set up can become tiresome because each request must specify which is the currency that should be used to show product prices, cart values and so on.

To solve this problem, the SDK checks for a "currency" attribute in the options object


client.products.list({category : '/some/category'}, {currency : 'USD'})
.then( function(response) {
  // Product prices are retrived in USD
})
    

Addresses

Create an address
Arguments
FieldTypeDescription
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)
.then(function(address){
  // Your code here
})
      
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)
  .then(function(data){
})
      
Retrieve an address

Retrieves an address by its id.

Example request

marketcloud.addresses.getById(881)
.then(function(data){
  // Your code here
})
      
Update an address

Updates an address by id.

Arguments
FieldTypeDescription
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)
.then(function(address){
  // Your code here
})
      
Delete an address

Deletes an address by id.

Example request

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

Brands

Retrieve a brand
Example request
//Retrieves a brand by its id
marketcloud.brands.getById(881)
.then(function(data){
  // Your code here
})
      
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

marketcloud.brands.list(query)
.then(function(data){
      })
Create a new brand
Arguments
FieldTypeDescription
name Required String String
image_url String The URL for the brand image/logo.
description String A description of the brand.
url String A label to be used in urls.
Example request

marketcloud.brands.create(new_brand)
.then(function(brand){
  // Your code here
})
      
Update a brand

Updates a brand by id.

Arguments
FieldTypeDescription
brand_id Required Number The univocal brand identifier
update_data Required Object An object containing the updates. See brands.create() for more informations.
Example request

marketcloud.brands.update(brand_id,new_brand)
.then(function(brand){
  // Your code here
})
      
Delete a brand

Deletes a brand by id.

Example request

marketcloud.brands.delete(brand_id)
.then(function(){
  // Your code here
})
      

Carts

Create a new cart

Creates a new cart with a product in it.

Arguments
FieldTypeDescription
user_id Number The univocal user identifier
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:


FieldTypeDescription
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.
Example request

marketcloud.carts.create({
            items:[{'product_id':5785,'quantity':2}]
        })
.then(function(data){
          // Your code here
        })
      
List all carts

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

Arguments
Field Type Description
user_id Number Display carts that belong to the user with the given 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 products to retrieve per page
page Number The page number of products to display
Example request

marketcloud.carts.list(query)
.then(function(data){
})
Retrieve a cart
Example request

marketcloud.carts.getById(cart_id)
.then(function(data){
  // Your code here
})
Add items to cart
Example request

        //Add products to a cart identified by its id
marketcloud.carts.add(cart_id,
        [{'product_id':5785,'quantity':2}])
.then(function(data){
  // Your code here
})
      
Update cart contents

Update quantities of products in cart or add new products to cart.

Example request

marketcloud.carts.update(testCart.id,[
  {'product_id':5712,'quantity':1},
  {'product_id':5785,'quantity':1}
])
.then(function(data){
  // Your code here
})
      
Remove items from cart
Example request

marketcloud.carts.remove(testCart.id,[
  {'product_id':5712},
  {'product_id':5785}
])
.then(function(data){
  // Your code here
})
      

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
  }])
.then(function(data){
          // Your code here
        })
        //Updates an item in the cart
marketcloud.carts.update(cart_id,[{
  'product_id':5785,
  'quantity':1,
  'variant_id' : 3
}])
.then(function(data){
          // Your code here
        })
        //Remove an item from the cart
marketcloud.carts.remove(cart_id,[{
  'product_id':5785,
  'variant_id' : 3
}])
.then(function(data){
          // Your code here
        })
      
Delete a cart

Deletes a cart by id.

Example request

marketcloud.carts.delete(cart_id)
.then(function(){
  // Your code here
})
      

Categories

Create a new category
Arguments
Attribute Type Description
name Required String The category name
description String A description of the category
image_url String The URL for the category image/logo
url String A label to be used in urls
parent_id Number Null if it is a category.
With a value represents the parent category identifier, and this is a subcategory
Example request

marketcloud.categories.create(new_category)
.then(function(category){
  // Your code here
})
      
List all categories

Retrieves a list of categories 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 categories to retrieve per page
page Number The page number of categories to display
Example request

marketcloud.categories.list(query)
.then(function(data){
  // Your code here
})
      
Retrieve a category

Retrieves a category by its id.

Example request

marketcloud.categories.getById(881)
.then(function(data){
  // Your code here
})               
Update a category

Updates a category by id.

Arguments
FieldTypeDescription
category_id Required Number The univocal category identifier
update_data Required Object An object containing the updates. See categories.create() for more informations.
Example request

marketcloud.categories.update(category_id,update_data)
.then(function(category){
  // Your code here
})
      
Delete a category

Deletes a category by id.

Example request

marketcloud.categories.delete(category_id)
.then(function(){
  // Your code here
})
      

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){
  
})
Create a new collection
Attribute Type Description
name Required String The name of the collection
slug String URL friendly string
Description String A description of the collection
items Array An array of collection entries, see the table below for more details
Collection entry
Attribute Type Description
product_id Required Number The id of the product entry.
variant_id Required Number The variant_id of the product entry
Example request

var new_collection = {
  "name" : "2017 Summer collection",
  "items" : [
    {"product_id" : 123, "variant_id" : 1 },
    {"product_id" : 123, "variant_id" : 4 },
    {"product_id" : 124, "variant_id" : 1 }
  ]
}
marketcloud.collections.create(new_collection)
.then(function(response){
  
})
.catch(function(error){
  
})
      
Update a collection

Updates a collection by id.

Arguments
FieldTypeDescription
collection_id Required Integer The univocal collection identifier
update_data Required Object An object containing the updates. See marketcloud.collections.create() for more informations.
Example request

// updates collection with it 123
marketcloud.collections.update(123, {"name" => "2018 Spring Collection"})
.then(function(response){
  
})
.catch(function(error){
  
})
      
Delete a collection

Deletes a collection by id.

Example request

// Delete collection with id 123
marketcloud.collections.delete(123)
.then(function(response){
  
})
.catch(function(error){
  
})
      

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});
      
Create a coupon
Parameters
Attribute Type Description
name Required String The coupon name
code Required String The secret code that the customer must match to benefit from the coupon.
target_type Required String This parameter tells the API where the coupon can be applied. Use 'CART_COUPON' if you want to apply a discount to the whole cart, 'PRODUCT_COUPON' if the discount is appliable only to a specific product, and 'CATEGORY_COUPON' if the discount can be applied to all products in a certain category.
discount_type Required String This parameter tells the API which is the type of discount. Use 'NET_REDUCTION' if you want to apply a net discount, or use 'PERCENTAGE_DISCOUNT' if you want to apply a percentage discount.
discount_value Required Number The value of the discount, if the discount_type is PERCENTAGE_DISCOUNT the discount_value represent the percentage of discount to apply (the percentage is calculated against the target, cart, product or category)
active Boolean Tells wether the coupon is active or not.
Example request
//Creates a new coupon worth 10$
var newCoupon = {
  "name" : "Welcome coupon 10$ discount",
  "code" : "XS671GH",
  "type" : "total",
  "target_type" : "CART_COUPON",
  "discount_type" : "NET_REDUCTION",
  "discount_value" : 10
}

marketcloud.coupons.create(newCoupon);
      
Updates a coupon
Example request
//Updates coupon, sets the discount value to 20
var couponUpdate = {
  name : "Welcome coupon 20$ discount",
  discount_value : 20
}
marketcloud.coupons.update(123,couponUpdate);
Delete a coupon
Example request
//Delete a coupon by its id
marketcloud.coupons.delete(123);
      

Orders

List all orders
Arguments
Field Type Description
user_id Number Filter orders 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 products to retrieve per page
page Number The page number of products to display
Example request

marketcloud.orders.list(query)
.then(function(data){
  // Your code here
})     
      
Retrieve an order
Example request

marketcloud.orders.getById(id)
.then(function(data){
  // Your code here
})     
      
Create a new order
Arguments
FieldTypeDescription
items Array An array of line items.This is required if the cart_id is missing.
cart_id Required Number The id of the cart that is going to be turned into an order. This is required if items is missing
state String The state of the order. Defaults to created
shipping_address_id Required Number The id of the shipping address
shipping_address Object A shipping address object. See Address for more informations. This is required if the shipping_address_id is missing.
billing_address_id Required Number The id of the billing address
billing_address Object A sbilling address object. See Address for more informations. This is required if the billing_address_id is missing.
user_id Number The id of the user making the order
store_id Number The id of the store receiving in the order
promotion_id Number The id of the promotion to apply.
coupon_code String The code of the coupon to apply.
payment_method_id Number The id of the custom payment method selected for the order.
shipping_id Number The id of the shipping method selected for the order.
Example request

var the_order = {
  shipping_address_id : 111,
  billing_address : 111,
  items : [{product_id : 1, quantiyt: 1}]
}
marketcloud.orders.create(the_order)
.then(function(data){
  // Your code here
})
      

Payments

Marketcloud supports a certain number of payment methods. Most of them requires client side and server side configuration, we try to abstract the server side part, so you just have to configure client side scripts.

You can find the list of payment methods supported by Marketcloud in your application's dashboard under the settings > payments page. There you will also find a link to the documentation related to each payment method.

Info
In order to create payments using a payment method, you must enable and configure that method in your dashboard.
Create a payment
Arguments
Field Type Description
method String A valid name of one of the supported payment methods. You can see a list of supported payment methods in Dashboard > settings > payments. If using Stripe, set it to "Stripe", set it to "Braintree" if using Braintree. If you want to use a custom payment method, set it to "Custom" and provide the payment_method_id parameter.
payment_method_id Number If you are using a custom payment method, privide that payment method's id here.
order_id Required Integer The id of the order related to this payment.
<attribute> Mixed Every payment method requires different additional parameters. Refer to the payment method documentation for more informations.
Example request

// Custom payment
var payment = {
  payment_method_id : 123
  order_id: created_order.id,
};

marketcloud.payments.create(payment);

// Braintree example
var payment = {
  method: 'Braintree',
  order_id: created_order.id,
  nonce: 'nonce-from-braintree.js'
};

marketcloud.payments.create(payment);


// Stripe example
var payment = {
  method: 'Stripe',
  order_id: created_order.id,
  source: 'value-from-stripe.js'
};

marketcloud.payments.create(payment);

// In both cases, nonce and source are obtained from Braintree
// and Stripe servers using their client side SDKs
      

Payment methods

Payment methods are a way to describe how customers will pay the goods they are buying. We have some default payment methods which are integrated into the system such as Braintree and Stripe, but your store might want some custom methods, such as cash on delivery.

Usage with orders

In order to tell Marketcloud that an order is using a certain payment method, just create an order with a payment_method_id value. See orders.create for an example

Create a payment method
//Creates a new payment method

var new_payment_method = {
    "name" : "Cash on delivery",
    "description" : "The order is paid at delivery.",
    "cost_type" : "fixed_fee",
    "fixed_fee" : 5,
    "active" : true
}

  marketcloud.paymentMethods.create(new_payment_method)
  .then( function(response){

  })
  .catch( function(error){

  })
Update a payment method
//Updates a new payment method
  marketcloud.paymentMethods.update({fixed_fee : 10})
  .then( function(response){
    //
  })
  .catch( function(error){
    //
  })
Delete a payment method
//Deletes a payment method with id 123
  marketcloud.paymentMethods.delete(123)
  .then( function(response){
    //
  })
  .catch( function(error){
    //
  })
Retrieve a payment method
//Retrieves a payment method by its id
  marketcloud.paymentMethods.getById(payment_method_id)
  .then( function(response){

  })
  .catch( function(error){

  })
List all payment methods
//Retrieves a list of payment methods filtered and sorted by the query object
  marketcloud.paymentMethods.list(query)
  .then( function(response){

  })
  .catch( function(error){
  
  })

Products

Create a product
Arguments
Parameter Type Description
name Required String The product name
sku String The product sku identifier
category_id Number The category identifier
brand_id Number The brand identifier
store_id Number The store identifier
description String A description for the product
price Required Number The product price
stock_type Required Number The stock type for the product
stock_level Number The stock level for the product
stock_status String The stock_status indicates whether the
published Boolean The status of the product
<attribute_name> Mixed This resource accepts custom attributes.
Example request
marketcloud.products.create(new_product)
.then(function(product){
  // Your code here
})
      
Retrieve a product

Retrieves a product by its id

Example request
marketcloud.products.getById(888)
.then(function(product){    
  // Your code here          
});
    
Example response

{
    "id": 13687,
    "name": "A song of fire and ice: A feast for crows",
    "sku": "ASOFAI_AFFC",
    "price": 7.79,
    "description": "A brief description of this book.",
    "published": true,
    "stock_level": 30,
    "stock_type": "track",
    "stock_status": null,
    "author": "George R. R. Martin",
    "isbn-10": "055358202X",
    "isbn-13": "978-0553582024",
    "pages": 1060,
    "editor": "Bantam Books",
    "genre": "Fantasy",
    "cover": "Paperback",
    "publication_year": "2001"
  }
    

Note that starting from author, the remaining fields are custom attributes defined when the product was created.

List all products

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

Arguments
Field Type Description
q String Filter results performing a text research on your products.
price_gt Number Display only products that cost more than the specified value.
price_lt Number Display only products that cost less than the specified value.
category_id Number Display products that belongs to a particular category.
brand_id Number Display products that belongs to a particular brand.
category String Display only products that belongs to the specified category path or to a sub category. For example, ?category=/shoes matches all producs in categories /shoes, /shoes/running /shoes/classic and other subcategories of "shoes"
<attribute_name> Mixed Filter products by any custom field.
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 products to retrieve per page
page Number The page number of products to display
currency String The currency code of the currency you want to use to show product prices.
Example request

var query = {category_id : 5,price_lt:50}
marketcloud.products.list(query)
.then(function(products){
          // Your code here
})
    

The previous example queries the api for products that belongs to the category with id equal to 5 and that cost less than 50

Update a product

Updates a product by id.

Arguments
FieldTypeDescription
product_id Required Number The univocal product identifier
update_data Required Object An object containing the updates. See products.create() for more informations.
Example request

marketcloud.products.update(product_id,update_data)
.then(function(product){
  // Your code here
})
    
Delete a product

Delete a product by id.

Example request

marketcloud.products.delete(product_id)
.then(function(){
  // Your code here
})
    

Promotions

Warning
This is a new feature, if you find some issue, please report at info@marketcloud.it. Also, note that you have to create promotions from the dashboard.
List promotions
Example request
//Retrieves a paginated list of promotions
marketcloud.promotions.get({"active" : true});
      
Create a promotion
Attribute Type Description
name Required String The name of the promotion
conditions Required Mixed An array of conditions, a condition is an object describing the rules under which a promotion can be applied to an order. See the table below for further information
effects Required Mixed An array of effects, an effect is an object describing the impact of the promotion on the final order. See the table below for further information
active Boolean If false, the promotion can not be used by any order.
Promotion condition model
Attribute Type Description
type Required String The type of the condition, possible values are 'MIN_NUMBER_OF_PRODUCTS' triggered when the cart has at least a certain number of products, 'MIN_CART_VALUE' triggered when the total value of the products in cart is greater than or equal to a certain value, 'CART_HAS_ITEM' when the cart contain a certain item.
value Required Number The value of the
Promotion effect model
Attribute Type Description
type Required String The type of the effect, possible values are 'CART_VALUE_PERCENTAGE_REDUCTION' will reduce the total cart value by a percentage value, 'CART_VALUE_NET_REDUCTION' will redduce the total cart value by a fixed value, 'CART_ITEMS_NET_REDUCTION' will reduce only the value of items by a fixed value, 'CART_ITEMS_PERCENTAGE_REDUCTION' will reduce only the value of items by a percentage value, FREE_SHIPPING will discount the value of shipping.
value Required Number The value of the effect.
Example request
//Creates a new promotion that grants 
//free shipping on order with a cart value above 70$ 
var newPromotion = {
  name : "Free shipping above 70$",
  conditions : [
    { type : "MIN_CART_VALUE", value:70 }
  ],
  effects : [
    {type : "FREE_SHIPPING", value: "FREE_SHIPPING"}
  ]
}
marketcloud.promotions.create(newPromotion);

//Creates a new promotion that grants 
//10% discount on each item on orders with a cart value above 70$ 
var newPromotion = {
  name : "10% discount above 70$",
  conditions : [
    { type : "MIN_CART_VALUE", value:70 }
  ],
  effects : [
    {type : "CART_ITEMS_PERCENTAGE_REDUCTION", value: 10}
  ]
}
marketcloud.promotions.create(newPromotion);


//Creates a new promotion that grants 
//10$ discount  on orders with a cart value above 70$ 
var newPromotion = {
  name : "10$ discount above 70$",
  conditions : [
    { type : "MIN_CART_VALUE", value:70 }
  ],
  effects : [
    {type : "CART_VALUE_NET_REDUCTION", value: 10}
  ]
}
marketcloud.promotions.create(newPromotion);
Updates a promotion
Example request
//We change the threshold for free shipping,
var promotionUpdate = {
  name : "Free shipping above 50$",
  conditions : [
    { type : "MIN_CART_VALUE", value : 50}
  ]
}

marketcloud.promotions.update(123,promotionUpdate);
      
Delete a promotion
Example request
//Delete a promotion with id 123
marketcloud.promotions.delete(123);
      
Retrieve a promotion
Example request
//Retrieves a promotion by its id
marketcloud.promotions.getById(123);
      
Get by cart

Retrieves a list of Promotions that can be applied to the given cart.

Arguments
Field Type Description
cart_id Integer Return only those promotion methods are compatibles with the cart with id cart_id
Example request

// Get eligible promotions for cart with id 1234
marketcloud.promotions.getByCart(1234);

Shippings

Retrieve a shipping
Example request
//Retrieves a shipping by its id
marketcloud.shippings.getById(123);
      
List all shippings

Retrieves a list of Shippings 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 shippings to retrieve per page
page Integer The page number of shippings to display
value Integer Return only those shipping methods that allow the wanted total value
weight Integer Return only those shipping methods that allow the wanted total weight
height Integer Return only those shipping methods that allow the wanted total height
depth Integer Return only those shipping methods that allow the wanted total depth
width Integer Return only those shipping methods that allow the wanted total width
Example request

// Get eligible shippings methods for orders
// with a total value of 50 $ (depends on currency)
// and a total weight of 40
marketcloud.shippings.list({
    "value" : 50,
    "weight" : 40
});
Create a new shipping
Arguments
Attribute Type Description
name Required String The shipping name
base_cost Required Number The base price for this shipping method.
per_item_cost Number The additional price for each item in the shipment.
min_value Number Orders with a total price greater than min_value are eligible for this shipping rule.
max_value Number Orders with a total price smaller than max_value are eligible for this shipping rule.
min_weight Number Orders with a total weight greater than min_weight are eligible for this shipping rule.
max_weight Number Orders with a total weight smaller than max_weight are eligible for this shipping rule.
min_width Number Orders with a total width greater than min_weight are eligible for this shipping rule.
max_width Number Orders with a total width smaller than max_width are eligible for this shipping rule.
min_height Number Orders with a total height greater than min_height are eligible for this shipping rule.
max_height Number Orders with a total height smaller than max_height are eligible for this shipping rule.
min_depth Number Orders with a total depth greater than min_depth are eligible for this shipping rule.
max_depth Number Orders with a total depth smaller than max_depth are eligible for this shipping rule.
Example request

// This shipping is eligible for orders with total value greater than 20
var new_shipping = {
  "name" : "Free shipping",
  "base_cost" : 0,
  "per_item_cost" : 0,
  "min_value" : 20
};
marketcloud.shippings.create(new_shipping);
      
Update a shipping

Updates a shipping by id.

Arguments
FieldTypeDescription
shipping_id Required Integer The univocal shipping identifier
update_data Required Object An object containing the updates. See marketcloud.shippings.create() for more informations.
Example request

// Updates a shipping method with id 123
marketcloud.shippings.update(123,{name : "Free shipping"});
      
Delete a shipping

Deletes a shipping by id.

Example request
marketcloud.shippings.delete(123);
      

Users

Authenticates a user
Example request

//Authenticates a user given email and password
marketcloud.users.authenticate('john.snow@wall.com','IKnowNothing')
.then(function(data){
  // Your code here
})
                
})      
      

If the authentication is successful, data is an object:


{
  "user" : {
    "email" : "john.doe@example.com",
    "full_name" : "John Doe"
  },
  "token" : "SECRET_TOKEN"
}
       

You can use the token to make calls on behalf of the user, but since the SDK works with admin credentials, you should avoid doing it.

Create a new user
Arguments
FieldTypeDescription
email Required String The user mail, must be less than 255 characters long.
name Required String The user name
password Required String The user password
image_url String The URL for the user image/logo.
<attribute_name> Mixed This resource accepts custom attributes.

Use this method to register users to you eCommerce app.

Example request

//Authenticates a user given email and password
marketcloud.users.create({
  name: "John Snow",
  email: "john.snow@thewall.com",
  password : "IknowKnothing"
})
.then(function(data){
  // Your code here
})      
      
List all users
Arguments
Field Type Description
<attribute_name> Mixed Filter users by any custom field.
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 products to retrieve per page
page Number The page number of products to display
Example request
marketcloud.users.list(query)
.then(function(data){
  // Your code here
})     
      
Retrieve a user
Example request

marketcloud.users.getById(888)
.then(function(data){
  // Your code here
})     
      
Update a user
Arguments
FieldTypeDescription
user_id Required Number The univocal user identifier
update_data Required Object An object containing the updates. See users.create() for more informations.
Example request

marketcloud.users.update(user_id,update_data)
  .then(function(data){
  // Your code here
})
      
Delete a user

Delete a user by id

Example request

marketcloud.users.delete(user_id)
.then(function(){
  // Your code here
})
      

Variables

List variables
Example request
//Retrieves a paginated list of variables
marketcloud.variables.list();
      
Create a variable
Model
Attribute Type Description
name Required String The variable name
value Required Mixed The value of your variable
type Required String This parameter tells the API the type of this variable, the possible values are string, number and boolean
Example request
//Creates a new variable
new_variable = {
  "name" : "google_analytics_code",
  "code" : "UA-127168162196",
  "type" : "string"
}

marketcloud.variables.create(new_variable);
      
Update a variable
Example request
//Updates a variable
marketcloud.variables.update({value : "newValue"});
      
Delete a variable
Example request
//Delete a variable by its id
marketcloud.variables.delete(id);
      
Retrieve a variable
Example request
//Retrieves a variable by its id
marketcloud.variables.getById(123);
      

Questions?

We're super happy to help with any question you might have! Send us an email, or get in touch with us in our Slack channel !