Navbar
Browser Node.js Python PHP

Introduction

Welcome to the DataCue API guide! This API documentation is to help you setup your e-commerce store to apply real time personalization to your website.

Sample code

We have code for your browser, Node, PHP and Python. You can view them in the dark area to the right. Click on the yellow tabs to switch the programming language. On a mobile device, switch the language using the hamburger menu on the top left.

Getting started

There are three major steps to complete the integration.

1. Import your historical data

This is a one-time run. Refer to the batch endpoints to send us all your existing orders, products and users (sometimes called customers).

2. Integrate future store data changes

Use the appropriate endpoints to ensure all updates to your store data are synchronized with DataCue.

This includes:

3. Integrate recommendations to your site with our JavaScript library

Refer to the store frontend section to understand all the events that you can send us via our JavaScript library. All events have sample code attached, just copy/paste them and change the values as appropriate.

Quick facts

API URL

The backend data API is located at https://api.datacue.co. The frontend events API is located at https://events.datacue.co.

Our javascript library interacts with events.datacue.co for you. This is why you don't see this URL in the frontend code samples.

Authentication

Replace API-key with your API key and API-secret with your API secret. Browser/frontend events only need your API key, while the other endpoints require both.

<?php

$apikey = "Your-API-Key-goes-here";
$apisecret = "Your-API-secret-goes-here";

$datacue = new \DataCue\Client($apikey, $apisecret);

$data = [
  "name"  => "Spongebob",
  "email" => "pineapple@underthe.sea"
];

$res = $datacue->users->create($data);

?>

import hashlib
import hmac
import json
import requests

url = "https://api.datacue.co/v1/users"
apikey = "your-api-key-goes-here"
apisecret = "your-api-secret-goes-here"

data = {
  "name" : 'Spongebob',
  "email" : 'pineapple@underthe.sea'
}
jsonData = json.dumps(data)

checksum = hmac.new(bytes(apisecret,'utf-8'), bytes(jsonData, 'utf-8'), hashlib.sha256)

response = requests.post(url, data=jsonData, auth=(apikey, checksum.hexdigest()))
const axios = require("axios");
const cryto = require("crypto");

const url = "https://api.datacue.co/v1/users";
const apikey = "your-api-key-goes-here";
const apisecret = "your-api-secret-goes-here";

const newUser = {
  name: "Spongebob",
  email: "pineapple@underthe.sea"
};

var hash = crypto
  .createHmac("sha256", apisecret)
  .update(JSON.Stringify(newUser));

//add to default authentication header
axios.defaults.auth = { username: "API-key", password: hash.digest("hex") };

axios.post(url, data);
<script>
  window.datacue.init("API-key");
</script>

Sample Headers

"Authorization": "Basic VGhpcyBpcyBhbiBlbmNvZGVkIHN0cmluZw=="
"Content-Type": "application/json"

You can find your API key and API secret in your DataCue Dashboard.

We use HTTP Basic Authentication, the username is your apikey and the password is a signed hash of the JSON payload you are sending. This way you don't need to send your actual API secret with the message. You get to keep it... a secret (sorry!).

The store frontend events are public so you only fill in the username field with your API key and leave the password blank. Our JavaScript library manages authentication for you. Just pass the apikey to the init() method and you're done. See code sample on the right.

For all other endpoints, we have reference implementations on how to sign your message with your apisecret in Node, PHP and Python.

Content-Type

Whenever you are sending us JSON (all endpoints except DELETE). Remember to set a content-type header to "application/json", some http libraries will do this for you automatically.

Content-Type: application/json

Store Frontend

Integrate DataCue to your storefront in two steps:

  1. Add our Javascript library and set a config object for all pages (except payment / order checkout pages)

  2. Include banner and product widgets to the pages you want to show recommendations

Include DataCue JS library

Remember to include the config snippet before the external scripts

<script>
  window.datacueConfig = {
    api_key: "your-api-key",
    user_id: "id of user (user_id field you send us for users)",
    page_type: "home" //can be many values, see the section 'Config object' on the left
  };
</script>
<script src="https://cdn.datacue.co/js/datacue.js"></script>
<script src="https://cdn.datacue.co/js/datacue-storefront.js"></script>
<?php
"browser only event (refer to the Browser tab)"
"browser only event (refer to the Browser tab)"
"browser only event (refer to the Browser tab)";

Place the snippets near the end of the <head> element of your main template. You should include it in these pages:

The config object

To properly set up tracking, you need to provide some information about the page that the user is currently visiting. You can do it by setting the following properties of the window.datacueConfig object:

Property Required Description
api_key Yes Your API key
user_id Yes (if logged in) If the visitor is not logged in, set the field to null
page_type Yes Current page type. Can be: home, product, category, cart, search, order confirmation or 404
product_id If page_type = 'product' On product pages, id of currently viewed product
product_update If page_type = 'product' See product pageview section below for details
category_id If page_type = 'category' On category pages, id of currently viewed category
category_update If page_type = 'category' See category pageview section below for details
order_id If page_type = 'order confirmation' On order confirmation pages, id of confirmed order
order_details If page_type = 'order confirmation' See order confirmation pageview section below for details
term If page_type = 'search' On search results page, current search term

Home page

Register a home pageview

<script>
  window.datacueConfig = {
    api_key: "your-api-key",
    user_id: "id of user / null if not logged in",
    page_type: "home"
  };
</script>
<script src="https://cdn.datacue.co/js/datacue.js"></script>
<script src="https://cdn.datacue.co/js/datacue-storefront.js"></script>
<?php
"browser only event (refer to the Browser tab)"
"browser only event (refer to the Browser tab)"
"browser only event (refer to the Browser tab)";

Place this code on your home page.

Product pages

Register a product pageview

<script>
  window.datacueConfig = {
    api_key: "your-api-key",
    user_id: "id of user / null if not logged in",
    page_type: "product",
    product_id: "p1",
    product_update: [
      {
        variant_id: "v1",
        name: "Blue Regular Fit Jeans",
        price: 99.5,
        full_price: 120,
        photo_url: "https://mycoolstore.com/images/p1.jpg",
        available: true,
        stock: 15,
        category_ids: ["jeans", "summer"],
        brand: "Zayra"
      },
      {
        variant_id: "v2",
        name: "Green Regular Fit Jeans",
        price: 99.5,
        full_price: 120,
        photo_url: "https://mycoolstore.com/images/p1.jpg",
        available: true,
        stock: 10,
        category_ids: ["jeans", "summer"],
        brand: "Zayra"
      }
    ]
  };
</script>
<script src="https://cdn.datacue.co/js/datacue.js"></script>
<script src="https://cdn.datacue.co/js/datacue-storefront.js"></script>
<?php
"browser only event (refer to the Browser tab)"
"browser only event (refer to the Browser tab)"
"browser only event (refer to the Browser tab)";

On product pages, you can also add an optional property product_update to the config object, to ensure that the most important information about your products is always synchronized.

product_update is an array, with each array element representing a variant of the product. e.g. [{variant_id:"v1",...},{variant_id:"v2",...}].

Property Description
name Name of the product
price Current price, after all discounts applied
full_price Base price without any discounts
photo_url URL of the main product photo
available true or false
stock Number of items remaining in stock
category_ids Array of product's category ids
brand Name of the brand

Category pages

Register a category pageview

<script>
  window.datacueConfig = {
    api_key: "your-api-key",
    user_id: "id of user / null if not logged in",
    page_type: "category",
    category_id: "jeans",
    category_update: {
      name: "Jeans",
      link: "/category/jeans"
    }
  };
</script>
<script src="https://cdn.datacue.co/js/datacue.js"></script>
<script src="https://cdn.datacue.co/js/datacue-storefront.js"></script>
<?php
"browser only event (refer to the Browser tab)"
"browser only event (refer to the Browser tab)"
"browser only event (refer to the Browser tab)";

On category pages, you can also add an optional property category_update to the config object, to ensure we keep category details in sync.

Property Description
name Display name of the category
link Relative URL to access category page

Search pages

Register a user search

<script>
  window.datacueConfig = {
    api_key: "your-api-key",
    user_id: "id of user / null if not logged in",
    page_type: "search",
    term: "blue jeans"
  };
</script>
<script src="https://cdn.datacue.co/js/datacue.js"></script>
<script src="https://cdn.datacue.co/js/datacue-storefront.js"></script>
<?php
"browser only event (refer to the Browser tab)"
"browser only event (refer to the Browser tab)"
"browser only event (refer to the Browser tab)";

Place this code on your search results page

Cart page

Register a cart pageview

<script>
  window.datacueConfig = {
    api_key: "your-api-key",
    user_id: "id of user / null if not logged in",
    page_type: "cart"
  };
</script>
<script src="https://cdn.datacue.co/js/datacue.js"></script>
<script src="https://cdn.datacue.co/js/datacue-storefront.js"></script>
<?php
"browser only event (refer to the Browser tab)"
"browser only event (refer to the Browser tab)"
"browser only event (refer to the Browser tab)";

Place this code on your cart page.

404 page

Register a 404 error pageview

<script>
  window.datacueConfig = {
    api_key: "your-api-key",
    user_id: "id of user / null if not logged in",
    page_type: "404"
  };
</script>
<script src="https://cdn.datacue.co/js/datacue.js"></script>
<script src="https://cdn.datacue.co/js/datacue-storefront.js"></script>
<?php
"browser only event (refer to the Browser tab)"
"browser only event (refer to the Browser tab)"
"browser only event (refer to the Browser tab)";

Place this code on your cart page.

Order confirmation

You can choose to send completed orders via the frontend or the backend.

Sending orders via backend (skip order_details object)

<script>
  window.datacueConfig = {
    api_key: "your-api-key",
    user_id: "id of user / email address if guest checkout",
    page_type: "order confirmation"
  };
</script>
<script src="https://cdn.datacue.co/js/datacue.js"></script>
<script src="https://cdn.datacue.co/js/datacue-storefront.js"></script>
<?php
"browser only event (refer to the Browser tab)"
"browser only event (refer to the Browser tab)"
"browser only event (refer to the Browser tab)";

Set the user_id field of the datacueConfig object to the user ID (if the user created an account) OR their email address (if it's a guest checkout).

Refer to create order on how to send order data via the backend.

Frontend

Sending orders via frontend

<script>
  window.datacueConfig = {
    api_key: "your-api-key",
    user_id: "id of user / email address if guest checkout",
    page_type: "order confirmation",
    order_id: "O123",
    order_details: {
      order_status: "completed",
      cart: [
        {
          product_id: "p1",
          variant_id: "v1",
          quantity: 1,
          unit_price: 24,
          currency: "USD"
        },
        {
          product_id: "p3",
          variant_id: "v2",
          quantity: 9,
          unit_price: 42,
          currency: "USD"
        }
      ],
      timestamp: "2018-04-04 23:29:04Z"
    }
  };
</script>
<script src="https://cdn.datacue.co/js/datacue.js"></script>
<script src="https://cdn.datacue.co/js/datacue-storefront.js"></script>
<?php
"browser only event (refer to the Browser tab)"
"browser only event (refer to the Browser tab)"
"browser only event (refer to the Browser tab)";

If you prefer to send order data from the frontend, you can include an optional property order_details to the config object. This allows you to send completed orders via the frontend instead of using any backend hooks.

order details object

Property Data Type Required Description
order_status String No Can be completed (default) or cancelled
cart Array Yes An array of line items in the order shopping cart (see below)
timestamp ISO-8601 Date No Order creation date/time in UTC timezone

cart object

Property Data Type Required Description
product_id String Yes Product ID code
variant_id String Yes Variant ID of the product
unit_price Decimal Yes The unit price of the product (including any discounts)
quantity Integer Yes Number of products purchased

Inserting banners

Implementing banners, you have two choices:

  1. DataCue's standard banner layout (recommended)
  2. Custom banner layout

If you choose the standard banner layout, a lot of things are already done for you like responsive design and a smooth loading process for each image. However, you must follow our banner size guidelines.

Custom layout means you need to implement responsive design yourself in exchange for (almost) total flexibility in banner sizes.

DataCue standard banner layout

<div
  data-dc-banners
  data-dc-static-img="path/to/your/banner.jpg"
  data-dc-static-link="link/to/chosen/category"
></div>
<?php
"browser only event (refer to the Browser tab)"
"browser only event (refer to the Browser tab)"
"browser only event (refer to the Browser tab)";

Custom banner layout

<!-- This is just an example, you can arrange the divs anyway you like -->

<div class="custom-banners">
  <div class="custom-static">
    <a href="https://example.com/any-link-you-want">
      <img src="https://example.com/some-banner-image.jpg" alt="" />
    </a>
  </div>
  <div class="custom-big" data-dc-main-insert-banner="1"></div>
  <div class="custom-big" data-dc-main-insert-banner="2"></div>
  <div class="custom-small" data-dc-sub-insert-banner="1"></div>
  <div class="custom-small" data-dc-sub-insert-banner="2"></div>
</div>
<?php
"browser only event (refer to the Browser tab)"
"browser only event (refer to the Browser tab)"
"browser only event (refer to the Browser tab)";

You can read all about banners in our usage guide

For full details on custom layouts for banners, refer to our advanced guide.

Inserting products

Product recommendations

<!-- insert all relevent product recommendations for current page type -->
<div data-dc-products></div>

<!-- ADVANCED: insert ONLY related/recommended products -->
<div data-dc-products="related"></div>

<!-- ADVANCED: insert ONLY recently viewed products -->
<div data-dc-products="recent"></div>

<!-- ADVANCED: insert ONLY similar products (product page only) -->
<div data-dc-products="similar"></div>

<!-- ADVANCED: insert ONLY dynamic categories (home page only)-->
<div data-dc-products="categories"></div>

<!-- ADVANCED: insert ONLY top products in category (category page only) -->
<div data-dc-products="top"></div>
<?php
"browser only event (refer to the Browser tab)"
"browser only event (refer to the Browser tab)"
"browser only event (refer to the Browser tab)";

We strongly recommend that you just insert the <div data-dc-products></div> wherever you want to see product recommendations. DataCue will automatically display the most appropriate product recommendations based on the page type. If you want to hide any type of recommendation, you can do it easily from your dashboard.

If you want to insert each recommendation in different areas of your website, you can specify a value for data-dc-products as shown in the code samples.

Types of recommendations

All pages (home, product, category, search, 404, cart etc)

  1. Related categories: Show multiple rows of products based on the product categories that best match the current customer's preferences.

  2. Related: Show top products that match the customer's preferences.

  3. Recently viewed: A list of all the products that were recently viewed by the user

Category page only

  1. Top: Show top products that are the most related to the current category being viewed based on your customers purchases.

Product page only

  1. Related: Show top products that are the most related to the current product being viewed based on your customers purchases.

Replaces the regular related carousel

  1. Similar: All products that are similar to the existing product looking at name, brand, categories and description.

Just insert one of the following snippets and we'll do the rest. You can control which recommendations you want to see and how many products in each section from your dashboard. You can also switch between grid and carousel widget types there.

Sending other events

This is an example of a typical browser event. Notice that context and timestamp aren't necessary when you're sending events directly from the user's browser.

{
  "user": {
    "user_id": "019mr8mf4r",
    "anonymous_id": "07d35b1a-5776-4ddf-8f1c-dd0d2db9c502",
    "profile": {
      "sex": "female",
      "location": "Santiago",
      "segment": "platinum"
    }
  },
  "event": {
    "type": "pageview",
    "subtype": "home"
  }
}

All events are registered in a similar format. There are 4 main objects in each request, described in detail in the next section.

Parameter Required Description
user Yes All data that we know about the current user at the time.
event Yes Details about the event
context No Details about the user’s device and location
timestamp No An ISO-8601 date string in UTC time for when the event happened

Parameter breakdown

User

FieldName Data Type Required Description
user_id String Yes (if logged in) The unique user id if the user has logged in
anonymous_id String Yes (if not logged in) An automatically generated visitor id if the user has not logged in.
profile JSON Object No Any user segmentation data you know about the user, see the table below for details.

User Profile (user.profile)

FieldName Data Type Required Description
sex String No Sex of the user
segment String No Custom segment name that you store e.g. Gold class / Member
location String No Location of the user as a commune, city, region or country

The above are the most common types of profile segments, since it's a JSON object you can specify any other fields you wish to use for personalization.

Event

Field descriptions differ per event type. Please refer to the event descriptions below to know what fields are required.

Context (optional)

We use incoming HTTP headers to fill in this object, therefore this object is optional. You can specify context if you are sending historical data, or have any other special requirements that require overriding the default headers.

Refer to the example json on the right to view the format.

  "context": {
    "ip": "12.34.56.78",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) AppleWebKit/604.5.6 (KHTML, like Gecko) Version/11.0.3 Safari/604.5.6"
  }
FieldName Data Type Required Description
ip String No IP address
user_agent String No User agent string of the browser

Timestamp (optional)

Only required if you're sending us historical events, if not, we log the event at the time we received it.

Refer to the example json on the right to view the format.

  "timestamp": "2018-01-23 00:30:08.276Z"
FieldName Data Type Required Description
timestamp ISO-8601 Date No The current time in UTC for when the event happened. E.g. "2017-11-01 00:29:03.123Z"

Cart update

<script>
  // assign user_id and user.profile if you haven't yet
  window.datacue.identify("019mr8mf4r", {
    sex: "female",
    location: "Santiago",
    segment: "platinum"
  });

  // track the event
  window.datacue.track({
    type: "cart",
    subtype: "update",
    cart: [
      {
        product_id: "p1",
        variant_id: "v1",
        quantity: 1,
        unit_price: 24,
        currency: "USD"
      },
      {
        product_id: "p2",
        variant_id: "v1",
        quantity: 1,
        unit_price: 24,
        currency: "USD"
      },
      {
        product_id: "p3",
        variant_id: "v1",
        quantity: 1,
        unit_price: 24,
        currency: "USD"
      }
    ],
    cart_link: "https://myshop.com/cart/123"
  });
</script>
<?php
"browser only event (refer to the Browser tab)"
"browser only event (refer to the Browser tab)"
"browser only event (refer to the Browser tab)";

The above command returns a 204 response code

Record whenever the users shopping cart changes. Whenever the user:

Request JSON fields

FieldName Data Type Required Description
type String Yes Set to 'cart'
subtype String Yes Set to 'update'
cart Array Yes Cart contents as an array of product, variant, unit price, quantity and currency
cart_link String Yes Link to view cart and resume shopping

Add product to wishlist

<script>
  // assign user_id and user.profile if you haven't yet
  window.datacue.identify("019mr8mf4r", {
    sex: "female",
    location: "Santiago",
    segment: "platinum"
  });

  // track the event
  window.datacue.track({
    type: "wishlist",
    subtype: "add",
    product_id: "p1",
    variant_id: "v2"
  });
</script>
<?php
"browser only event (refer to the Browser tab)"
"browser only event (refer to the Browser tab)"
"browser only event (refer to the Browser tab)";

The above command returns a 204 response code

Record changes to user's wishlist when a new product is added to it.

Request JSON fields

FieldName Data Type Required Description
type String Yes Set to 'wishlist'
subtype String Yes Set to 'add'
product_id String Yes Set to product id being added
variant_id String No Set to product's variant id (if applicable)

Remove product from wishlist

<script>
  // assign user_id and user.profile if you haven't yet
  window.datacue.identify("019mr8mf4r", {
    sex: "female",
    location: "Santiago",
    segment: "platinum"
  });

  // track the event
  window.datacue.track({
    type: "wishlist",
    subtype: "remove",
    product_id: "p1",
    variant_id: "v2"
  });
</script>
<?php
"browser only event (refer to the Browser tab)"
"browser only event (refer to the Browser tab)"
"browser only event (refer to the Browser tab)";

The above command returns a 204 response code

Record changes to user's wishlist when a product is removed from it.

Request JSON fields

FieldName Data Type Required Description
type String Yes Set to 'wishlist'
subtype String Yes Set to 'remove'
product_id String Yes Set to product id being removed
variant_id String No Set to product's variant id (if applicable)

Checkout started

<script>
  // assign user_id and user.profile if you haven't yet
  window.datacue.identify("019mr8mf4r", {
    sex: "female",
    location: "Santiago",
    segment: "platinum"
  });

  // track the event
  window.datacue.track({
    type: "checkout",
    subtype: "started",
    cart: [
      {
        product_id: "p1",
        variant: "v1",
        quantity: 1,
        unit_price: 24,
        currency: "USD"
      },
      {
        product_id: "p2",
        variant: "v2",
        quantity: 3,
        unit_price: 39,
        currency: "USD"
      }
    ],
    cart_link: "https://myshop.com/cart/123"
  });
</script>
<?php
"browser only event (refer to the Browser tab)"
"browser only event (refer to the Browser tab)"
"browser only event (refer to the Browser tab)";

The above command returns a 204 response code

Record the moment the user initiates the check out process, typically from their shopping cart.

Request JSON fields

FieldName Data Type Required Description
type String Yes Set to 'checkout'
subtype String Yes Set to 'started'
cart Array Yes Cart contents as an array of product, variant, unit price, quantity and currency
cart_link String Yes Link to view cart and resume shopping

User Login

<script>
  // assign user_id and user.profile if you haven't yet
  window.datacue.identify("019mr8mf4r", {
    sex: "female",
    location: "Santiago",
    segment: "platinum"
  });

  // track the event
  window.datacue.track({
    type: "login"
  });
</script>
<?php
"browser only event (refer to the Browser tab)"
"browser only event (refer to the Browser tab)"
"browser only event (refer to the Browser tab)";

The above command returns a 204 response code

Record a login event by a user on your website, if the user login is cached, you do not need to fire this event when the user returns.

Request JSON fields

FieldName Data Type Required Description
type String Yes Set to 'login'

Optional Events

You don't need to implement those if you're using our scripts.

Home pageview

<script>
  // assign user_id and user.profile if you haven't yet
  window.datacue.identify("019mr8mf4r", {
    sex: "female",
    location: "Santiago",
    segment: "platinum"
  });

  // track the event
  window.datacue
    .track({
      type: "pageview",
      subtype: "home"
    })
    .then(function (response) {
      // see response structure below
    });
</script>
<?php
"browser only event (refer to the Browser tab)"
"browser only event (refer to the Browser tab)"
"browser only event (refer to the Browser tab)";

The above command returns JSON structured like this:

{
  "main_banners": [
    {
      "link": "/category/bathroom",
      "name": "",
      "banner_id": "B1",
      "photo_url": "/banners/bathroom/bathroom-min.jpeg"
    }
  ],
  "sub_banners": [
    {
      "link": "/category/bathroom/organizer",
      "name": "",
      "banner_id": "B6",
      "photo_url": "/banners/bathroom/subbanner_organizer.jpeg"
    },
    {
      "link": "/category/bathroom/racks",
      "name": "",
      "banner_id": "B7",
      "photo_url": "/banners/bathroom/subbanner_racks.jpeg"
    },
    {
      "link": "/category/bathroom/towels",
      "name": "",
      "banner_id": "B8",
      "photo_url": "/banners/bathroom/subbanner_towels.jpeg"
    }
  ],
  "related_product_skus": [
    {
      "link": "/product/double-bed-2",
      "name": "Luxury Double Bed",
      "price": 1299,
      "photo_url": "/products/18.jpg",
      "category_1": "bedroom",
      "product_id": "18"
    },
    {
      "link": "/product/sofa-4",
      "name": "Contemporary Sofa",
      "price": 329,
      "photo_url": "/products/59.jpg",
      "category_1": "living-room",
      "product_id": "59"
    },
    {
      "link": "/product/cutleries-2",
      "name": "Decorative Flatware",
      "price": 79,
      "photo_url": "/products/41.jpg",
      "category_1": "kitchen",
      "product_id": "41"
    },
    {
      "link": "/product/organizer-4",
      "name": "Scandinavian Organizer",
      "price": 69,
      "photo_url": "/products/12.jpg",
      "category_1": "bathroom",
      "product_id": "12"
    }
  ],
  "recent_product_skus": [
    {
      "product_id": "18",
      "variant_id": "a",
      "name": "Luxury Double Bed",
      "price": "1299.00",
      "photo_url": "/products/18.jpg",
      "link": "/product/double-bed-2",
      "extra": {
        "discount": "20%"
      }
    }
  ]
}

Request banner and product recommendations when a user visits your home page

Request JSON fields

FieldName Data Type Required Description
type String Yes Set to 'pageview'
subtype String Yes Set to 'home'

Response JSON fields

FieldName Data Type Description
main_banners Array An array of banner objects recommended for the current user
sub_banners Array An array of sub banner objects recommended for the current user
related_product_skus Array An array of product objects recommended for the current user
recent_product_skus Array A live list of the last products the current user has viewed

Product pageview

<script>
  // assign user_id and user.profile if you haven't yet
  window.datacue.identify("019mr8mf4r", {
    sex: "female",
    location: "Santiago",
    segment: "platinum"
  });

  // track the event
  window.datacue
    .track({
      type: "pageview",
      subtype: "product",
      product_id: "p1",
      variant_id: "v1"
    })
    .then(function (response) {
      // see response structure below
    });
</script>
<?php
"browser only event (refer to the Browser tab)"
"browser only event (refer to the Browser tab)"
"browser only event (refer to the Browser tab)";

The above command returns JSON structured like this:

{
  "similar_product_skus": [
    {
      "link": "/product/sofa-1",
      "name": "Soft Sofa",
      "price": 299,
      "photo_url": "/products/56.jpg",
      "category_1": "living-room",
      "product_id": "56"
    },
    {
      "link": "/product/outdoor-sofa-3",
      "name": "Wicker Sofa",
      "price": 299,
      "photo_url": "/products/38.jpg",
      "category_1": "outdoors",
      "product_id": "38"
    },
    {
      "link": "/product/single-bed-1",
      "name": "Basic Bed",
      "price": 299,
      "photo_url": "/products/16.jpg",
      "category_1": "bedroom",
      "product_id": "16"
    },
    {
      "link": "/product/rack-2",
      "name": "Handicraft Rack",
      "price": 49,
      "photo_url": "/products/6.jpg",
      "category_1": "bathroom",
      "product_id": "6"
    }
  ],
  "related_product_skus": null,
  "recent_product_skus": [
    {
      "product_id": "18",
      "variant_id": "a",
      "name": "Luxury Double Bed",
      "price": "1299.00",
      "photo_url": "/products/18.jpg",
      "link": "/product/double-bed-2",
      "extra": {}
    }
  ]
}

Request product recommendations when a user visits a product page

Request JSON fields

FieldName Data Type Required Description
type String Yes Set to 'pageview'
subtype String Yes Set to 'product'
product_id String Yes Set to product id being viewed
variant_id String No Set to product's variant id (if applicable)

Response JSON fields

FieldName Data Type Description
similar_product_skus Array An array of product objects with similar characteristics to the current product
related_product_skus Array An array of product objects that are frequently bought with the current product
recent_product_skus Array A live list of the last products the current user has viewed

Category pageview

<script>
  // assign user_id and user.profile if you haven't yet
  window.datacue.identify("019mr8mf4r", {
    sex: "female",
    location: "Santiago",
    segment: "platinum"
  });

  // track the event
  window.datacue.track({
    type: "pageview",
    subtype: "category",
    category_id: "living-room"
  });
</script>
<?php
"browser only event (refer to the Browser tab)"
"browser only event (refer to the Browser tab)"
"browser only event (refer to the Browser tab)";

The above command returns a 204 response code

Pages showing multiple products on a page, these are commonly called category, collection or catalog pages.

Request JSON fields

FieldName Data Type Required Description
type String Yes Set to 'pageview'
subtype String Yes Set to 'category'
category_id String Yes Set to the id of the category being viewed
<script>
  // assign user_id and user.profile if you haven't yet
  window.datacue.identify("019mr8mf4r", {
    sex: "female",
    location: "Santiago",
    segment: "platinum"
  });

  // track the event
  window.datacue
    .track({
      type: "search",
      term: "tables"
    })
    .then(function (response) {
      // see response structure below
    });
</script>
<?php
"browser only event (refer to the Browser tab)"
"browser only event (refer to the Browser tab)"
"browser only event (refer to the Browser tab)";

The above command returns JSON structured like this:

{
  "recent_product_skus": [
    {
      "product_id": "18",
      "variant_id": "a",
      "name": "Luxury Double Bed",
      "price": "1299.00",
      "photo_url": "/products/18.jpg",
      "link": "/product/double-bed-2",
      "extra": {
        "discount": "20%"
      }
    }
  ]
}

Record when a user performs a search on your website

Request JSON fields

FieldName Data Type Required Description
type String Yes Set to 'search'
term String Yes Set to the user's search term

Response JSON fields

FieldName Data Type Description
recent_product_skus Array A live list of the last products the current user has viewed
<script>
  // assign user_id and user.profile if you haven't yet
  window.datacue.identify("019mr8mf4r", {
    sex: "female",
    location: "Santiago",
    segment: "platinum"
  });

  // track the event
  // NOTE: passing true as 2nd argument will defer
  // the event until next page load (helpful if your
  // shop is not a single page app)
  window.datacue.track(
    {
      type: "click",
      subtype: "banner",
      banner_id: "b1",
      category_id: "c1"
    },
    true
  );
</script>
<?php
"browser only event (refer to the Browser tab)"
"browser only event (refer to the Browser tab)"
"browser only event (refer to the Browser tab)";

The above command returns a 204 response code

Record clicks to a banner or a sub banner, typically on your home page

Request JSON fields

FieldName Data Type Required Description
type String Yes Set to 'click'
subtype String Yes Set to 'banner'
banner_id String Yes Set to the id of the clicked banner

Product click

<script>
  // assign user_id and user.profile if you haven't yet
  window.datacue.identify("019mr8mf4r", {
    sex: "female",
    location: "Santiago",
    segment: "platinum"
  });

  // track the event
  // NOTE: passing true as 2nd argument will defer
  // the event until next page load (helpful if your
  // shop is not a single page app)
  window.datacue.track(
    {
      type: "click",
      subtype: "product",
      product_id: "p2"
    },
    true
  );
</script>
<?php
"browser only event (refer to the Browser tab)"
"browser only event (refer to the Browser tab)"
"browser only event (refer to the Browser tab)";

The above command returns a 204 response code

Record clicks on a product anywhere on your website.

Request JSON fields

FieldName Data Type Required Description
type String Yes Set to 'click'
subtype String Yes Set to 'related', 'similar' or 'recent'
product_id String Yes Set to the id of the clicked product

Overview

Summary

<!--- backend only event (refer to the Python, PHP or Node tab) -->
<?php

$apikey = "Your-API-Key-goes-here";
$apisecret = "Your-API-secret-goes-here";

$datacue = new \DataCue\Client($apikey, $apisecret);

$res = $this->client->overview->all();

print($res);

?>

import hashlib
import hmac
import requests

url = "https://api.datacue.co/v1/overview"
apikey = "your-api-key-goes-here"
apisecret = "your-api-secret-goes-here"

checksum = hmac.new(bytes(apisecret, "utf-8"),
                    bytes("", "utf-8"), hashlib.sha256)

response = requests.get(url, auth=(apikey, checksum.hexdigest()))

print(response.json())

const axios = require("axios");
const cryto = require("crypto");

const url = "https://api.datacue.co/v1/overview";
const apikey = "your-api-key-goes-here";
const apisecret = "your-api-secret-goes-here";

var hash = crypto.createHmac("sha256", apisecret).update("");

//add to default authentication header
axios.defaults.auth = { username: "API-key", password: hash.digest("hex") };

axios
  .get(url)
  .then((response) => {
    if (response.data) {
      console.log(response.data);
    }
  })
  .catch((err) => {
    console.err(err);
  });

The above command returns a 200 response code

{
  "categories": 300,
  "products": { "products": 500, "variants": 2500 },
  "orders": 5000,
  "users": 4900
}

Endpoint: GET https://api.datacue.co/v1/overview Provides an overview of all backend data received by the DataCue API from your store.

Response JSON fields

FieldName Data Type Description
categories Integer Number of categories received
products Integer Number of unique product received (excluding variants)
variants Integer Number of unique product variants received
orders Integer Number of unique orders received
users Integer Number of unique users received

Get Products

<!--- backend only event (refer to the Python, PHP or Node tab) -->
<?php

$apikey = "Your-API-Key-goes-here";
$apisecret = "Your-API-secret-goes-here";

$datacue = new \DataCue\Client($apikey, $apisecret);

$res = $this->client->overview->products();

print($res);

?>

import hashlib
import hmac
import requests

url = "https://api.datacue.co/v1/overview/products"
apikey = "your-api-key-goes-here"
apisecret = "your-api-secret-goes-here"

checksum = hmac.new(bytes(apisecret, "utf-8"),
                    bytes("", "utf-8"), hashlib.sha256)

response = requests.get(url, auth=(apikey, checksum.hexdigest()))

print(response.json())

const axios = require("axios");
const cryto = require("crypto");

const url = "https://api.datacue.co/v1/overview/products";
const apikey = "your-api-key-goes-here";
const apisecret = "your-api-secret-goes-here";

var hash = crypto.createHmac("sha256", apisecret).update("");

//add to default authentication header
axios.defaults.auth = { username: "API-key", password: hash.digest("hex") };

axios
  .get(url)
  .then((response) => {
    if (response.data) {
      console.log(response.data);
    }
  })
  .catch((err) => {
    console.err(err);
  });

The above command returns a 200 response code

{ "ids": ["P1", "P2"], "count": 2 }

Endpoint: GET https://api.datacue.co/v1/overview/products Provides an overview of all product data received by the DataCue API from your store.

Response JSON fields

Field Data Type Description
ids String Array Array of all product ids received successfully
count Integer Number of unique products

Get Categories

<!--- backend only event (refer to the Python, PHP or Node tab) -->
<?php

$apikey = "Your-API-Key-goes-here";
$apisecret = "Your-API-secret-goes-here";

$datacue = new \DataCue\Client($apikey, $apisecret);

$res = $this->client->overview->categories();

print($res);

?>

import hashlib
import hmac
import requests

url = "https://api.datacue.co/v1/overview/categories"
apikey = "your-api-key-goes-here"
apisecret = "your-api-secret-goes-here"

checksum = hmac.new(bytes(apisecret, "utf-8"),
                    bytes("", "utf-8"), hashlib.sha256)

response = requests.get(url, auth=(apikey, checksum.hexdigest()))

print(response.json())

const axios = require("axios");
const cryto = require("crypto");

const url = "https://api.datacue.co/v1/overview/categories";
const apikey = "your-api-key-goes-here";
const apisecret = "your-api-secret-goes-here";

var hash = crypto.createHmac("sha256", apisecret).update("");

//add to default authentication header
axios.defaults.auth = { username: "API-key", password: hash.digest("hex") };

axios
  .get(url)
  .then((response) => {
    if (response.data) {
      console.log(response.data);
    }
  })
  .catch((err) => {
    console.err(err);
  });

The above command returns a 200 response code

{ "ids": ["C1", "C2"], "count": 2 }

Endpoint: GET https://api.datacue.co/v1/overview/categories Provides an overview of all categories received by the DataCue API from your store.

Response JSON fields

Field Data Type Description
ids String Array Array of all categoriy ids received successfully
count Integer Number of unique categories

Get Orders

<!--- backend only event (refer to the Python, PHP or Node tab) -->
<?php

$apikey = "Your-API-Key-goes-here";
$apisecret = "Your-API-secret-goes-here";

$datacue = new \DataCue\Client($apikey, $apisecret);

$res = $this->client->overview->orders();

print($res);

?>

import hashlib
import hmac
import requests

url = "https://api.datacue.co/v1/overview/orders"
apikey = "your-api-key-goes-here"
apisecret = "your-api-secret-goes-here"

checksum = hmac.new(bytes(apisecret, "utf-8"),
                    bytes("", "utf-8"), hashlib.sha256)

response = requests.get(url, auth=(apikey, checksum.hexdigest()))

print(response.json())

const axios = require("axios");
const cryto = require("crypto");

const url = "https://api.datacue.co/v1/overview/orders";
const apikey = "your-api-key-goes-here";
const apisecret = "your-api-secret-goes-here";

var hash = crypto.createHmac("sha256", apisecret).update("");

//add to default authentication header
axios.defaults.auth = { username: "API-key", password: hash.digest("hex") };

axios
  .get(url)
  .then((response) => {
    if (response.data) {
      console.log(response.data);
    }
  })
  .catch((err) => {
    console.err(err);
  });

The above command returns a 200 response code

{ "ids": ["O1", "O2"], "count": 2 }

Endpoint: GET https://api.datacue.co/v1/overview/orders Provides an overview of all order data received by the DataCue API from your store.

Response JSON fields

Field Data Type Description
ids String Array Array of all order ids received successfully
count Integer Number of unique orders

Get Users

<!--- backend only event (refer to the Python, PHP or Node tab) -->
<?php

$apikey = "Your-API-Key-goes-here";
$apisecret = "Your-API-secret-goes-here";

$datacue = new \DataCue\Client($apikey, $apisecret);

$res = $this->client->overview->users();

print($res);

?>

import hashlib
import hmac
import requests

url = "https://api.datacue.co/v1/overview/users"
apikey = "your-api-key-goes-here"
apisecret = "your-api-secret-goes-here"

checksum = hmac.new(bytes(apisecret, "utf-8"),
                    bytes("", "utf-8"), hashlib.sha256)

response = requests.get(url, auth=(apikey, checksum.hexdigest()))

print(response.json())

const axios = require("axios");
const cryto = require("crypto");

const url = "https://api.datacue.co/v1/overview/users";
const apikey = "your-api-key-goes-here";
const apisecret = "your-api-secret-goes-here";

var hash = crypto.createHmac("sha256", apisecret).update("");

//add to default authentication header
axios.defaults.auth = { username: "API-key", password: hash.digest("hex") };

axios
  .get(url)
  .then((response) => {
    if (response.data) {
      console.log(response.data);
    }
  })
  .catch((err) => {
    console.err(err);
  });

The above command returns a 200 response code

{ "ids": ["U1", "U2"], "count": 2 }

Endpoint: GET https://api.datacue.co/v1/overview/users Provides an overview of all user data received by the DataCue API from your store.

Response JSON fields

Field Data Type Description
ids String Array Array of all users ids received successfully
count Integer Number of unique users

Products

Create Product

<!--- backend only event (refer to the Python, PHP or Node tab) -->
<?php

$apikey = "Your-API-Key-goes-here";
$apisecret = "Your-API-secret-goes-here";

$datacue = new \DataCue\Client($apikey, $apisecret);

$data = [
  "product_id" => "p1",
  "variant_id" => "v1",
  "category_ids" => ["men","summer","jeans"],
  "type" => ["jeans"],
  "tags" => "featured, premium",
  "name" => "cool jeans",
  "brand" => "zayra",
  "description" => "very fashionable jeans",
  "color" => "blue",
  "size" => "M",
  "price" => 25000,
  "full_price" => 30000,
  "available" => true,
  "stock" => 5,
  "rating" => 90,
  "extra" => [
    "extra_feature" => "details"
  ],
  "photo_url" => "https://s3.amazon.com/image.png",
  "link" => "/product/p1",
  "owner_id" => "user_id_3"
];

$res = $datacue->products->create($data);

?>

import hashlib
import hmac
import json
import requests

url = "https://api.datacue.co/v1/products"
apikey = "your-api-key-goes-here"
apisecret = "your-api-secret-goes-here"

data = {
  "product_id": "p1",
  "variant_id": "v1",
  "category_ids": ["men","summer","jeans"],
  "type" : ["jeans"],
  "tags" : "featured, premium",
  "name": "cool jeans",
  "brand": "zayra",
  "description": "very fashionable jeans",
  "color": "blue",
  "size": "M",
  "price": 25000,
  "full_price": 35000,
  "available": True,
  "stock": 5,
  "rating": 90,
  "extra": {
    "extra_feature": "details"
  },
  "photo_url": "https://s3.amazon.com/image.png",
  "link": "/product/p1",
  "owner_id": "user_id_3"
}


jsonData = json.dumps(data)
checksum = hmac.new(bytes(apisecret, 'utf-8'),
                    bytes(jsonData, 'utf-8'), hashlib.sha256)

response = requests.post(url, data=jsonData, auth=(apikey, checksum.hexdigest()))
const axios = require("axios");
const cryto = require("crypto");

const url = "https://api.datacue.co/v1/products";
const apikey = "your-api-key-goes-here";
const apisecret = "your-api-secret-goes-here";

const data = {
  product_id: "p1",
  variant_id: "v1",
  category_ids: ["men", "summer", "jeans"],
  type: ["jeans"],
  tags: "featured, premium",
  name: "cool jeans",
  brand: "zayra",
  description: "very fashionable jeans",
  color: "blue",
  size: "M",
  price: 25000,
  full_price: 35000,
  available: true,
  stock: 5,
  rating: 90,
  extra: {
    extra_feature: "details"
  },
  photo_url: "https://s3.amazon.com/image.png",
  link: "/product/p1",
  owner_id: "user_id_3"
};

var hash = crypto.createHmac("sha256", apisecret).update(JSON.Stringify(data));

//add to default authentication header
axios.defaults.auth = { username: "API-key", password: hash.digest("hex") };

axios.post(url, data);

The above command returns a 201 response code

Endpoint: POST https://api.datacue.co/v1/products Whenever a new product is created, send this request from your backend.

Request JSON fields

FieldName Data Type Required Description
product_id String Yes The product id or SKU number
variant_id String Yes A unique variant id within the product id, if you only use product SKUs set this to a constant such as 'no-variants'
category_ids String Array Yes A list of all the matching category ids as tags e.g. ["Jeans","Summer","Men"]. Must be a valid category_id (see categories)
type String No Type of product
tags String No Any tags assigned to the product
name String Yes Name or Title of the product
brand String No Brand name of the product
description String No Long text description of the product
color String No Color of the product
size String No Size of the product
price Decimal Yes Current price including any discounts to two decimal places e.g. 4.50
full_price Decimal Yes Full price without discount to two decimal places e.g. 5.30
available Boolean No Is the product available for Sale (Default true)
stock Integer Yes Number of product in stock
rating Integer No Rating from 0-100 of the product/variant
extra JSON Object No Any other fields you want to store about the product that you want to display on site e.g. discounts or promotions.
photo_url String Yes URL of the photo, you can use relative URLs as this is purely for your front-end to request the image
link String Yes URL of product page for this product e.g. /products/p1
owner_id String No If you're running a marketplace, store the product's owner or seller's user ID here.

Discounts

DataCue can feature your discounted products automatically. Use the price and full_price field when you have a discount. If full_price is empty or less than price, we assume the product is not on discount.

Lets say you have a product that usually costs $50. This week, it's on discount and costs $40. Update the product like so:

Rating

DataCue can display a star rating under each product recommendation if you collect user reviews or have any other kind of rating system. Just send us a value from 0-100 in the rating field. This will appear as 5 stars under each product. e.g. a rating of 58, will show a star rating of 3 filled in stars out of 5.

Update Product

<!--- backend only event (refer to the Python, PHP or Node tab) -->
<?php

$apikey = "Your-API-Key-goes-here";
$apisecret = "Your-API-secret-goes-here";

$datacue = new \DataCue\Client($apikey, $apisecret);

// replace $productId with the actual values you want to update
$productId = "p1";
// replace $variantId with the actual values you want to update
$variantId = "v1";
$data = [
  "category_ids" => ["men","summer","jeans"],
  "name" => "cool jeans",
  "brand" => "zayra",
  "type" => "shorts",
  "tags" => "promo, homepage",
  "description" => "very fashionable jeans",
  "color" => "blue",
  "size" => "M",
  "price" => 25000,
  "full_price" => 30000,
  "available" => true,
  "stock" => 5,
  "rating" => 90,
  "extra" => [
    "extra_feature" => "details"
  ],
  "photo_url" => "https://s3.amazon.com/image.png",
  "link" => "/product/p1",
  "owner_id" => "user_id_3"
];

$res = $datacue->products->update($productId, $variantId, $data);


import hashlib
import hmac
import json
import requests

productId = "p1";
variantId = "v1";

url = f"https://api.datacue.co/v1/products/{productId}/{variantId}"
apikey = "your-api-key-goes-here"
apisecret = "your-api-secret-goes-here"

data = {
  "category_ids": ["men","summer","jeans"],
  "name": "cool jeans",
  "brand": "zayra",
  "type": "shorts",
  "tags": "promo, homepage",
  "description": "very fashionable jeans",
  "color": "blue",
  "size": "M",
  "price": 25000,
  "full_price": 35000,
  "available": True,
  "stock": 5,
  "rating": 90,
  "extra": {
    "extra_feature": "details"
  },
  "photo_url": "https://s3.amazon.com/image.png",
  "link": "/product/p1",
  "owner_id": "user_id_3"
}

jsonData = json.dumps(data)
checksum = hmac.new(bytes(apisecret, 'utf-8'),
                    bytes(jsonData, 'utf-8'), hashlib.sha256)

response = requests.put(url, data=jsonData, auth=(apikey, checksum.hexdigest()))
const axios = require("axios");
const cryto = require("crypto");

const productId = "p1";
const variantId = "v1";

const url = `https://api.datacue.co/v1/products/${productId}/${variantId}`;
const apikey = "your-api-key-goes-here";
const apisecret = "your-api-secret-goes-here";

const data = {
  category_ids: ["men", "summer", "jeans"],
  name: "cool jeans",
  brand: "zayra",
  type: "shorts",
  tags: "promo, homepage",
  description: "very fashionable jeans",
  color: "blue",
  size: "M",
  price: 25000,
  full_price: 35000,
  available: true,
  stock: 5,
  rating: 90,
  extra: {
    extra_feature: "details"
  },
  photo_url: "https://s3.amazon.com/image.png",
  link: "/product/p1",
  owner_id: "user_id_3"
};

var hash = crypto.createHmac("sha256", apisecret).update(JSON.Stringify(data));

//add to default authentication header
axios.defaults.auth = { username: apikey, password: hash.digest("hex") };

axios.put(url, data);

The above command returns a 204 response code

Endpoint: PUT https://api.datacue.co/v1/products/<product_id>/<variant_id>

Whenever an existing product is updated such as image, name, price or new discounts, send this request from your backend.

Request JSON fields

Same as for Create Product, except product_id and variant_id.

Delete Product

<!--- backend only event (refer to the Python, PHP or Node tab) -->
<?php

$apikey = "Your-API-Key-goes-here";
$apisecret = "Your-API-secret-goes-here";

$datacue = new \DataCue\Client($apikey, $apisecret);

// replace $productId with the actual value you want to delete
$productId = "p1";
// replace $variantId with the actual value you want to delete
$variantId = "v1";

// if you want to delete a variant
$res = $datacue->products->delete($productId, $variantId);

// if you want to delete a product and all associated variants
$res = $datacue->products->delete($productId);


import hashlib
import hmac
import json
import requests

# replace these values with the product and variant id you want to delete
productId = "p1"
variantId = "v1"

url = f"https://api.datacue.co/v1/products/{productId}/{variantId}"

apikey = "your-api-key-goes-here"
apisecret = "your-api-secret-goes-here"

checksum = hmac.new(bytes(apisecret,'utf-8'), bytes("", 'utf-8'), hashlib.sha256)

response = requests.delete(url, auth=(apikey, checksum.hexdigest()))
const axios = require("axios");
const cryto = require("crypto");

// replace these values with the product and variant id you want to delete
const productId = "p1";
const variantId = "v1";

const url = `https://api.datacue.co/v1/products/${productId}/${variantId}`;
const apikey = "your-api-key-goes-here";
const apisecret = "your-api-secret-goes-here";

var hash = crypto.createHmac("sha256", apisecret).update("");

//add to default authentication header
axios.defaults.auth = { username: apikey, password: hash.digest("hex") };

axios.delete(url);

The above command returns a 204 response code

Delete a product on your system.

Delete a variant

Endpoint: DELETE https://api.datacue.co/v1/products/<product_id>/<variant_id>

Delete a product and all associated variants

Endpoint: DELETE https://api.datacue.co/v1/products/<product_id>

Categories

Create Category

<!--- backend only event (refer to the Python, PHP or Node tab) -->
<?php

$apikey = "Your-API-Key-goes-here";
$apisecret = "Your-API-secret-goes-here";

$datacue = new \DataCue\Client($apikey, $apisecret);

$data = [
  "category_id" => "summer-jeans",
  "name" => "Summer Jeans",
  "link" => "/categories/summer-jeans",
  "active" => true
];

$res = $datacue->categories->create($data);

import hashlib
import hmac
import json
import requests

url = "https://api.datacue.co/v1/categories"
apikey = "your-api-key-goes-here"
apisecret = "your-api-secret-goes-here"

data = {
  "category_id": "summer-jeans",
  "name": "Summer Jeans",
  "link": "/categories/summer-jeans",
  "active": True
}

jsonData = json.dumps(data)
checksum = hmac.new(bytes(apisecret,'utf-8'), bytes(jsonData, 'utf-8'), hashlib.sha256)

response = requests.post(url, data=jsonData, auth=(apikey, checksum.hexdigest()))

const axios = require('axios');
const cryto = require('crypto');

const url = 'https://api.datacue.co/v1/categories'
const apikey = 'your-api-key-goes-here';
const apisecret = 'your-api-secret-goes-here';

const data = {
  category_id: 'summer-jeans'
  name: 'Summer Jeans'
  link: '/categories/summer-jeans'
};

var hash = crypto.createHmac('sha256', apisecret).update(JSON.Stringify(data));

//add to default authentication header
axios.defaults.auth = { username: 'API-key', password: hash.digest('hex') };

axios.post(url, data);

The above command returns a 201 response code

Endpoint: POST https://api.datacue.co/v1/categories

When a new category is created on your store

Request JSON fields

FieldName Data Type Required Description
category_id String Yes The unique category id assigned
name String Yes Category friendly name
link String Yes Link to the respective category's page

Update Category

<!--- backend only event (refer to the Python, PHP or Node tab) -->
<?php

$apikey = "Your-API-Key-goes-here";
$apisecret = "Your-API-secret-goes-here";

$datacue = new \DataCue\Client($apikey, $apisecret);

// replace $userId with the actual value you want to update
$categoryId = "summer-jeans";
$data = [
  "name" => "Summer Jeans Special",
  "link" => "/categories/summer-jeans-2"
];

$res = $datacue->category->update($categoryId, $data);

import hashlib
import hmac
import json
import requests

# replace this value with the user id you want to update
categoryId = "summer-jeans"

url = f"https://api.datacue.co/v1/category/{categoryId}"
apikey = "your-api-key-goes-here"
apisecret = "your-api-secret-goes-here"

data = {
  "name" : "Summer Jeans Special",
  "link" : "/categories/summer-jeans-2"
}

jsonData = json.dumps(data)
checksum = hmac.new(bytes(apisecret,'utf-8'), bytes(jsonData, 'utf-8'), hashlib.sha256)

response = requests.put(url, data=jsonData, auth=(apikey, checksum.hexdigest()))
const axios = require("axios");
const cryto = require("crypto");

// replace this value with the user id you want to update
const categoryId = "summer-jeans";

const url = `https://api.datacue.co/v1/categories/${categoryId}`;
const apikey = "your-api-key-goes-here";
const apisecret = "your-api-secret-goes-here";

const data = {
  name: "Summer Jeans Special",
  link: "/categories/summer-jeans-2"
};

var hash = crypto.createHmac("sha256", apisecret).update(JSON.Stringify(data));

//add to default authentication header
axios.defaults.auth = { username: apikey, password: hash.digest("hex") };

axios.put(url, data);

The above command returns a 204 response code

Endpoint: PUT https://api.datacue.co/v1/categories/<category_id>

Send any updates to your category objects with this endpoint.

Request JSON fields

Same as for Create Category, except category_id.

Delete Category

<!--- backend only event (refer to the Python, PHP or Node tab) -->
<?php

$apikey = "Your-API-Key-goes-here";
$apisecret = "Your-API-secret-goes-here";

$datacue = new \DataCue\Client($apikey, $apisecret);

// replace $userId with the actual value you want to delete
$categoryId = "summer-jeans";

$res = $datacue->categories->delete($categoryId);

import hashlib
import hmac
import json
import requests

# replace this value with the user id you want to delete
categoryId = "summer-jeans"

url = f"https://api.datacue.co/v1/categories/{categoryId}"
apikey = "your-api-key-goes-here"
apisecret = "your-api-secret-goes-here"

checksum = hmac.new(bytes(apisecret,'utf-8'), bytes("", 'utf-8'), hashlib.sha256)

response = requests.delete(url, auth=(apikey, checksum.hexdigest()))

const axios = require("axios");
const cryto = require("crypto");

// replace this value with the user id you want to delete
const categoryId = "summer-jeans";

const url = `https://api.datacue.co/v1/categories/${categoryId}`;
const apikey = "your-api-key-goes-here";
const apisecret = "your-api-secret-goes-here";

var hash = crypto.createHmac("sha256", apisecret).update("");

//add to default authentication header
axios.defaults.auth = { username: apikey, password: hash.digest("hex") };

axios.delete(url);

The above command returns a 204 response code

Endpoint: DELETE https://api.datacue.co/v1/categories/<category_id>

When a product category is deleted from your system.

Users

Create User

<!--- backend only event (refer to the Python, PHP or Node tab) -->
<?php

$apikey = "Your-API-Key-goes-here";
$apisecret = "Your-API-secret-goes-here";

$datacue = new \DataCue\Client($apikey, $apisecret);

$data = [
  "user_id" => "u1",
  "email" => "spongebob@bikinibottom.com",
  "title" => "Mr",
  "first_name" => "Spongebob",
  "last_name" => "Squarepants",
  "profile" => [
    "loyalty_plan" => "platinum"
  ],
  "wishlist" => ["p1", "p3", "p4"], //array of product ids
  "email_subscriber" => true,
  "guest_account" => false,
  "timestamp" => "2018-04-04 23:29:04-0300"
];

$res = $datacue->users->create($data);

import hashlib
import hmac
import json
import requests

url = "https://api.datacue.co/v1/users"
apikey = "your-api-key-goes-here"
apisecret = "your-api-secret-goes-here"

data = {
  "user_id" : "u1",
  "email" : "spongebob@bikinibottom.com",
  "title" : "Mr",
  "first_name" : "Spongebob",
  "last_name" : "Squarepants",
  "profile" : {
    "loyalty_plan" : "platinum"
  },
  "wishlist" : ["p1", "p3", "p4"], # array of product ids
  "email_subscriber" : True,
  "guest_account" : False,
  "timestamp" : "2018-04-04 23:29:04-0300"
}

jsonData = json.dumps(data)
checksum = hmac.new(bytes(apisecret,'utf-8'), bytes(jsonData, 'utf-8'), hashlib.sha256)

response = requests.post(url, data=jsonData, auth=(apikey, checksum.hexdigest()))

const axios = require("axios");
const cryto = require("crypto");

const url = "https://api.datacue.co/v1/users";
const apikey = "your-api-key-goes-here";
const apisecret = "your-api-secret-goes-here";

const data = {
  user_id: "u1",
  email: "spongebob@bikinibottom.com",
  title: "Mr",
  first_name: "Spongebob",
  last_name: "Squarepants",
  profile: {
    loyalty_plan: "platinum"
  },
  wishlist: ["p1", "p3", "p4"], // array of product ids
  email_subscriber: true,
  guest_account: false,
  timestamp: "2018-04-04 23:29:04-0300"
};

var hash = crypto.createHmac("sha256", apisecret).update(JSON.Stringify(data));

//add to default authentication header
axios.defaults.auth = { username: "API-key", password: hash.digest("hex") };

axios.post(url, data);

The above command returns a 201 response code

Endpoint: POST https://api.datacue.co/v1/users

When a new user has successfully signed up / registered on your system.

Request JSON fields

FieldName Data Type Required Description
user_id String Yes The unique user id assigned
anonymous_id String No Anonymous ID that was previously associated with this user prior to user sign up
email String Yes, if using email marketing User's email address
title String No Salutation e.g. Mr., Ms., Dr.
first_name String No User's first name, if you store all the names in one field assign the name to this field
last_name String No User's last name
profile JSON Object No User profile information, like if they are on a loyalty program.
email_subscriber Boolean No Has this user consented to receive marketing email?
guest_account Boolean No Is this a guest account (user has no login credentials)
wishlist Array No An array of product ids representing the products the user has on their wishlist.
timestamp ISO-8601 Date No User creation date/time in UTC timezone

Update User

<!--- backend only event (refer to the Python, PHP or Node tab) -->
<?php

$apikey = "Your-API-Key-goes-here";
$apisecret = "Your-API-secret-goes-here";

$datacue = new \DataCue\Client($apikey, $apisecret);

// replace $userId with the actual value you want to update
$userId = "u1";
$data = [
  "email" => "xyz@abc.com",
  "title" => "Mr",
  "first_name" => "John",
  "last_name" => "Smith",
  "profile" => [
    "loyalty_plan" => "platinum"
  ],
  "wishlist" => ["P1", "P3", "P4"], //array of product ids
  "email_subscriber" => true,
  "guest_account" => false,
  "timestamp" => "2018-04-04 23:29:04-0300"
];

$res = $datacue->users->update($userId, $data);

import hashlib
import hmac
import json
import requests

# replace this value with the user id you want to update
userId = "u1"

url = f"https://api.datacue.co/v1/users/{userId}"
apikey = "your-api-key-goes-here"
apisecret = "your-api-secret-goes-here"

data = {
  "user_id": "u1",
  "email": "xyz@abc.com",
  "title": "Mr",
  "first_name": "John",
  "last_name": "Smith",
  "profile": {
    "loyalty_plan": "platinum"
  },
  "wishlist": ['P1','P3','P4'], #array of product ids
  "email_subscriber": True,
  "guest_account": False,
  "timestamp": "2018-04-04 23:29:04-0300"
}

jsonData = json.dumps(data)
checksum = hmac.new(bytes(apisecret,'utf-8'), bytes(jsonData, 'utf-8'), hashlib.sha256)

response = requests.put(url, data=jsonData, auth=(apikey, checksum.hexdigest()))
const axios = require("axios");
const cryto = require("crypto");

// replace this value with the user id you want to update
const userId = "u1";

const url = `https://api.datacue.co/v1/users/${userId}`;
const apikey = "your-api-key-goes-here";
const apisecret = "your-api-secret-goes-here";

const data = {
  email: "xyz@abc.com",
  title: "Mr",
  first_name: "Noob",
  last_name: "Saibot",
  profile: {
    loyalty_plan: "platinum"
  },
  wishlist: ["P1", "P3", "P4"], //array of product ids
  email_subscriber: true,
  guest_account: false,
  timestamp: "2018-04-04 23:29:04-0300"
};

var hash = crypto.createHmac("sha256", apisecret).update(JSON.Stringify(data));

//add to default authentication header
axios.defaults.auth = { username: apikey, password: hash.digest("hex") };

axios.put(url, data);

The above command returns a 204 response code

Endpoint: PUT https://api.datacue.co/v1/users/<user_id>

When the user makes changes to their profile or when they configure any relevant preferences. For instance if they unsubscribe from receiving marketing email, this is very important to know.

Request JSON fields

Same as for Create User, except user_id.

Delete User

<!--- backend only event (refer to the Python, PHP or Node tab) -->
<?php

$apikey = "Your-API-Key-goes-here";
$apisecret = "Your-API-secret-goes-here";

$datacue = new \DataCue\Client($apikey, $apisecret);

// replace $userId with the actual value you want to delete
$userId = "u1";

$res = $datacue->users->delete($userId);

import hashlib
import hmac
import json
import requests

# replace this value with the user id you want to delete
userId = "u1"

url = f"https://api.datacue.co/v1/users/{userId}"
apikey = "your-api-key-goes-here"
apisecret = "your-api-secret-goes-here"

checksum = hmac.new(bytes(apisecret,'utf-8'), bytes("", 'utf-8'), hashlib.sha256)

response = requests.delete(url, auth=(apikey, checksum.hexdigest()))

const axios = require("axios");
const cryto = require("crypto");

// replace this value with the user id you want to delete
const userId = "u1";

const url = `https://api.datacue.co/v1/users/${userId}`;
const apikey = "your-api-key-goes-here";
const apisecret = "your-api-secret-goes-here";

var hash = crypto.createHmac("sha256", apisecret).update("");

//add to default authentication header
axios.defaults.auth = { username: apikey, password: hash.digest("hex") };

axios.delete(url);

The above command returns a 204 response code

Endpoint: DELETE https://api.datacue.co/v1/users/<user_id>

When a user account is deleted from your system.

Orders

Create Order

<!-- Refer to the store frontend section above to see frontend code samples -->
<?php

$apikey = "Your-API-Key-goes-here";
$apisecret = "Your-API-secret-goes-here";

$datacue = new \DataCue\Client($apikey, $apisecret);

$data = [
  "order_id" => "O123",
  "user_id" => "U456",
  "order_status" => "completed",
  "cart" => [
    ["product_id" => "p1", "variant_id" => "v1", "quantity" => 1, "unit_price" => 24, "currency" => "USD"],
    ["product_id" => "p3", "variant_id" => "v2", "quantity" => 9, "unit_price" => 42, "currency" => "USD"]
  ],
  "timestamp" => "2018-04-04 23:29:04Z"
];

$res = $datacue->orders->create($data);

import hashlib
import hmac
import json
import requests

url = "https://api.datacue.co/v1/orders"
apikey = "your-api-key-goes-here"
apisecret = "your-api-secret-goes-here"

data = {
  "order_id": "o123",
  "user_id": "u456",
  "order_status": "completed",
  "cart": [
    {
      "product_id": "p1",
      "variant_id": "v1",
      "quantity": 1,
      "unit_price": 24,
      "currency": "USD"
    },
    {
      "product_id": "p3",
      "variant_id": "v2",
      "quantity": 9,
      "unit_price": 42,
      "currency": "USD"
    }
  ],
  "timestamp": "2018-04-04 23:29:04Z"
}

jsonData = json.dumps(data)
checksum = hmac.new(bytes(apisecret,'utf-8'), bytes(jsonData, 'utf-8'), hashlib.sha256)

response = requests.post(url, data=jsonData, auth=(apikey, checksum.hexdigest()))
const axios = require("axios");
const cryto = require("crypto");

const url = "https://api.datacue.co/v1/orders";
const apikey = "your-api-key-goes-here";
const apisecret = "your-api-secret-goes-here";

const data = {
  order_id: "O123",
  user_id: "U456",
  order_status: "completed",
  cart: [
    {
      product_id: "p1",
      variant_id: "v1",
      quantity: 1,
      unit_price: 24,
      currency: "USD"
    },
    {
      product_id: "p3",
      variant_id: "v2",
      quantity: 9,
      unit_price: 42,
      currency: "USD"
    }
  ],
  timestamp: "2018-04-04 23:29:04Z"
};

var hash = crypto.createHmac("sha256", apisecret).update(JSON.Stringify(data));

//add to default authentication header
axios.defaults.auth = { username: "API-key", password: hash.digest("hex") };

axios.post(url, data);

The above command returns a 201 response code

Orders can be sent in two ways. The easiest way is to insert your order data into the datacueConfig object in the order confirmation page. Look at the 'browser' tab code samples to see how to do it.

Alternatively, you can use our REST api to send it.

Endpoint: POST https://api.datacue.co/v1/orders

An Order is considered 'completed' as soon as the checkout process is completed on your website. It does not matter if the order has further steps such as waiting for payment, or order fulfilment.

Request JSON fields

FieldName Data Type Required Description
order_id String Yes The unique order id assigned
user_id String Yes User ID that made the order
order_status String No Can be completed (default) or cancelled
cart Array No An array of line items in the order shopping cart
timestamp ISO-8601 Date Yes Order creation date/time in UTC timezone

cart items

FieldName Data Type Required Description
product_id String Yes Product ID code
variant_id String Yes Variant ID of the product
unit_price Decimal Yes The unit price of the product (including any discounts)
quantity Integer Yes Number of products purchased

Guest checkout

Guest checkouts are when a customer does not need to create an account with a password to make a purchase.

To create a guest checkout, you just need to do two things.

  1. Set the user_id to the email of the guest account.

  2. If you are sending order data via the REST api, you must add a snippet to the order confirmation page. Switch the code samples to 'Browser' to see the snippet.

<script>
  window.datacueConfig = {
    api_key: "your-api-key",
    user_id: "<guest-email-id>",
    page_type: "order confirmation"
  };
</script>

<script src="https://cdn.datacue.co/js/datacue.js"></script>
<script src="https://cdn.datacue.co/js/datacue-storefront.js"></script>

Change Order Status

Order status can be completed or cancelled.

<!--- backend only event (refer to the Python, PHP or Node tab) -->
<?php

$apikey = "Your-API-Key-goes-here";
$apisecret = "Your-API-secret-goes-here";

$datacue = new \DataCue\Client($apikey, $apisecret);

// replace $orderId with the order id you want to modify
$orderId = 'o1';

$res = $datacue->orders->cancel($orderId); //to cancel order
$res = $datacue->orders->complete($orderId); //to complete order

import hashlib
import hmac
import json
import requests

# replace this value with the order id you want to modify
orderId = "o1"

url = f"https://api.datacue.co/v1/orders/{orderId}/status"
apikey = "your-api-key-goes-here"
apisecret = "your-api-secret-goes-here"

data = {
  "order_status": "cancelled"
}

jsonData = json.dumps(data)
checksum = hmac.new(bytes(apisecret,'utf-8'), bytes(jsonData, 'utf-8'), hashlib.sha256)

response = requests.patch(url, data=jsonData, auth=(apikey, checksum.hexdigest())
const axios = require("axios");
const cryto = require("crypto");

// replace this value with the order id you want to modify
const orderId = "o1";

const url = `https://api.datacue.co/v1/orders/${orderId}/status`;
const apikey = "your-api-key-goes-here";
const apisecret = "your-api-secret-goes-here";

const data = {
  order_status: "cancelled"
};

var hash = crypto.createHmac("sha256", apisecret).update(JSON.Stringify(data));

//add to default authentication header
axios.defaults.auth = { username: apikey, password: hash.digest("hex") };

axios.patch(url, data);

The above command returns a 204 response code

Orders cannot be cancelled via the browser API. You MUST use the more secure REST API to do so.

Endpoint: PATCH https://api.datacue.co/v1/orders/<order_id>/status

Request JSON fields

Field Data Type Required Description
order_status String Yes Can be completed or cancelled

Delete Order

<!--- backend only event (refer to the Python, PHP or Node tab) -->
<?php

$apikey = "Your-API-Key-goes-here";
$apisecret = "Your-API-secret-goes-here";

$datacue = new \DataCue\Client($apikey, $apisecret);

// replace $orderId with the actual value you want to delete
$orderId = 'o1';

$res = $datacue->orders->delete($orderId);

import hashlib
import hmac
import json
import requests

# replace this value with the order id you want to delete
orderId = "o1"

url = f"https://api.datacue.co/v1/orders/{orderId}"
apikey = "your-api-key-goes-here"
apisecret = "your-api-secret-goes-here"

checksum = hmac.new(bytes(apisecret,'utf-8'), bytes("", 'utf-8'), hashlib.sha256)

response = requests.delete(url, auth=(apikey, checksum.hexdigest()))
const axios = require("axios");
const cryto = require("crypto");

// replace this value with the order id you want to delete
const orderId = "o1";

const url = `https://api.datacue.co/v1/orders/${orderId}`;
const apikey = "your-api-key-goes-here";
const apisecret = "your-api-secret-goes-here";

var hash = crypto.createHmac("sha256", apisecret).update("");

//add to default authentication header
axios.defaults.auth = { username: apikey, password: hash.digest("hex") };

axios.delete(url);

The above command returns a 204 response code

Orders cannot be deleted via the browser or frontend. You MUST use the REST API to do so as it's more secure.

Endpoint: DELETE https://api.datacue.co/v1/orders/<order_id>

When an order is deleted from your system.

Batch

Best explained with an example: lets say you want to create 500 products in one go. As seen in the previous section, a product create payload looks like this:

{
  "product_id": "P1",
  "variant_id": "V2",
  "category_ids": ["jeans"],
  "price": 50,
  "photo_url": "/products/p1.jpg",
  "link": "/products/p1"
}

To submit multiple, just send an array of product create requests like so:

[
  {
    "product_id": "P1",
    "variant_id": "V2",
    "category_ids": ["jeans"],
    "price": 50,
    "photo_url": "/products/p1.jpg",
    "link": "/products/p1"
  },
  {
    "product_id": "P2",
    "variant_id": "V1",
    "category_ids": ["shirts"],
    "price": 30,
    "photo_url": "/products/p2.jpg",
    "link": "/products/p2"
  }
]

Use the batch endpoint if you want to do a bulk import, typically when you first start using DataCue and you want to add your historical orders, products or users.

Send an array of the items in the payload, we accept a maximum of 500 items per request.

Create/Update Products

<!--- backend only event (refer to the Python, PHP or Node tab) -->
<?php

$apikey = "Your-API-Key-goes-here";
$apisecret = "Your-API-secret-goes-here";

$datacue = new \DataCue\Client($apikey, $apisecret, $options, $env);

// batch create products
$productDataList = [
    [
        "product_id" => "p1",
        "variant_id" => "v1",
        "category_ids" => ["jeans","men","summer"],
        "name" => "cool jeans",
        "brand" => "zayra",
        "description" => "very fashionable jeans",
        "color" => "blue",
        "size" => "M",
        "price" => 99,
        "full_price" => 119,
        "stock" => 5,
        "extra" => [
            "extra_feature" => "details"
        ],
        "photo_url" => "https://s3.amazon.com/image.png",
        "link" => "/product/p1",
        "owner_id" => "user_id_3"
    ], [
        "product_id" => "p2",
        "variant_id" => "v2",
        "category_ids" => ["hats","women","summer"],
        "name" => "summer hat",
        "brand" => "zayra",
        "description" => "very fashionable hat",
        "color" => "black",
        "size" => "",
        "price" => 24,
        "full_price" => 30,
        "stock" => 5,
        "extra" => [
            "extra_feature" => "details"
        ],
        "photo_url" => "https://s3.amazon.com/image.png",
        "link" => "/product/p2",
        "owner_id" => "user_id_3"
    ]
];
$res = $datacue->products->batchCreate($productDataList);

import hashlib
import hmac
import json
import requests

url = "https://api.datacue.co/v1/batch/products"
apikey = "your-api-key-goes-here"
apisecret = "your-api-secret-goes-here"

data = [
  {
    "product_id" : "p1",
    "variant_id" : "v1",
    "category_ids" : ["jeans","men","summer"],
    "name" : "cool jeans",
    "brand" : "zayra",
    "description" : "very fashionable jeans",
    "color" : "blue",
    "size" : "M",
    "price" : 99,
    "full_price" : 119,
    "stock" : 5,
    "extra" : {
        "extra_feature": "details"
    },
    "photo_url" : "https://s3.amazonaws.com/image.png",
    "link" : "/product/p1"
  }, {
    "product_id" : "p2",
    "variant_id" : "v2",
    "category_ids" : ["hats","women","summer"],
    "name" : "summer hat",
    "brand" : "zayra",
    "description" : "very fashionable hat",
    "color" : "black",
    "size" : "",
    "price" : 24,
    "full_price" : 30,
    "stock" : 5,
    "extra" : {
        "extra_feature": "details"
    },
    "photo_url": "https://s3.amazonaws.com/image.png",
    "link": "/product/p2"
  }
]

jsonData = json.dumps(data)
checksum = hmac.new(bytes(apisecret,'utf-8'),
  bytes(jsonData, 'utf-8'),
  hashlib.sha256)

response = requests.post(url, data=jsonData, auth=(apikey, checksum.hexdigest()))
const axios = require("axios");
const cryto = require("crypto");

const url = "https://api.datacue.co/v1/batch/products";
const apikey = "your-api-key-goes-here";
const apisecret = "your-api-secret-goes-here";

const data = [
  {
    product_id: "p1",
    variant_id: "v1",
    category_ids: ["jeans", "men", "summer"],
    name: "cool jeans",
    brand: "zayra",
    description: "very fashionable jeans",
    color: "blue",
    size: "M",
    price: 99,
    full_price: 119,
    stock: 5,
    extra: {
      extra_feature: "details"
    },
    photo_url: "https://s3.amazonaws.com/image.png",
    link: "/product/p1"
  },
  {
    product_id: "p2",
    variant_id: "v2",
    category_ids: ["hats", "women", "summer"],
    name: "summer hat",
    brand: "zayra",
    description: "very fashionable hat",
    color: "black",
    size: "",
    price: 24,
    full_price: 30,
    stock: 5,
    extra: {
      extra_feature: "details"
    },
    photo_url: "https://s3.amazonaws.com/image.png",
    link: "/product/p2"
  }
];

var hash = crypto.createHmac("sha256", apisecret).update(JSON.Stringify(data));

//add to default authentication header
axios.defaults.auth = { username: "API-key", password: hash.digest("hex") };

axios.post(url, data);

Endpoint: POST https://api.datacue.co/v1/batch/products

Request JSON

An array of product objects

The above command returns a 201 response code

Create/Update Categories

<!--- backend only event (refer to the Python, PHP or Node tab) -->
<?php

$apikey = "Your-API-Key-goes-here";
$apisecret = "Your-API-secret-goes-here";

$datacue = new \DataCue\Client($apikey, $apisecret, $options, $env);

// batch create categories
$categoryDataList = [
    [
        "category_id" => "c1",
        "name" => "jeans",
        "link" => "/category/jeans"
    ], [
        "category_id" => "c2",
        "name" => "shoes",
        "link" => "/category/shoes"
    ]
];
$res = $datacue->categories->batchCreate($categoryDataList);

import hashlib
import hmac
import json
import requests

url = "https://api.datacue.co/v1/batch/categories"
apikey = "your-api-key-goes-here"
apisecret = "your-api-secret-goes-here"

data = [
  {
    "category_id" : "c1",
    "name" : "jeans",
    "link" : "/categories/jeans"
  }, {
    "category_id" : "c2",
    "name" : "shoes",
    "link" : "/categories/shoes"
  }
]

jsonData = json.dumps(data)
checksum = hmac.new(bytes(apisecret,'utf-8'),
  bytes(jsonData, 'utf-8'),
  hashlib.sha256)

response = requests.post(url, data=jsonData, auth=(apikey, checksum.hexdigest()))
const axios = require("axios");
const cryto = require("crypto");

const url = "https://api.datacue.co/v1/batch/products";
const apikey = "your-api-key-goes-here";
const apisecret = "your-api-secret-goes-here";

const data = [
  {
    category_id: "c1",
    name: "jeans",
    link: "/categories/jeans"
  },
  {
    category_id: "c2",
    name: "shoes",
    link: "/categories/shoes"
  }
];

var hash = crypto.createHmac("sha256", apisecret).update(JSON.Stringify(data));

//add to default authentication header
axios.defaults.auth = { username: "API-key", password: hash.digest("hex") };

axios.post(url, data);

Endpoint: POST https://api.datacue.co/v1/batch/categories

Request JSON fields

Array of categories

The above command returns a 201 response code

Create Orders

<!--- backend only event (refer to the Python, PHP or Node tab) -->
<?php

$apikey = "Your-API-Key-goes-here";
$apisecret = "Your-API-secret-goes-here";

$datacue = new \DataCue\Client($apikey, $apisecret, $options, $env);

$orderDataList = [
    [
        "order_id" => "o1",
        "user_id" => "u1",
        "cart" => [
            ["product_id" => "p1", "variant_id" => "v1", "quantity" => 1, "unit_price" => 24, "currency" => "USD"],
            ["product_id" => "p2", "variant_id" => "v2", "quantity" => 9, "unit_price" => 42, "currency" => "USD"],
        ],
        "timestamp" => "2018-04-04 23:29:04Z",
    ], [
        "order_id" => "o2",
        "user_id" => "u1",
        "cart" => [
            ["product_id" => "p1", "variant_id" => "v1", "quantity" => 1, "unit_price" => 24, "currency" => "USD"],
            ["product_id" => "p2", "variant_id" => "v2", "quantity" => 9, "unit_price" => 42, "currency" => "USD"],
        ],
        "timestamp" => "2018-04-04 23:29:04Z",
    ]
];
$res = $datacue->orders->batchCreate($orderDataList);

import hashlib
import hmac
import json
import requests

url = "https://api.datacue.co/v1/batch/orders"
apikey = "your-api-key-goes-here"
apisecret = "your-api-secret-goes-here"

data = [
{
  "order_id" : "o1",
  "user_id" : "u1",
  "cart" : [
      {"product_id":  "p1", "variant_id" : "v1", "quantity" : 1, "unit_price":  24, "currency" : "USD"},
      {"product_id":  "p2", "variant_id" : "v2", "quantity" : 9, "unit_price":  42, "currency" : "USD"}
  ],
  "timestamp": "2018-04-04 23:29:04Z"
}, {
  "order_id" : "o2",
  "user_id" : "u1",
  "cart" : [
      {"product_id" : "p1", "variant_id" : "v1", "quantity" : 1, "unit_price" : 24, "currency" : "USD"},
      {"product_id" : "p2", "variant_id" : "v2", "quantity" : 9, "unit_price" : 42, "currency" : "USD"}
  ],
  "timestamp" : "2018-04-04 23:29:04Z"
}]

jsonData = json.dumps(data)
checksum = hmac.new(bytes(apisecret,'utf-8'),
  bytes(jsonData, 'utf-8'),
  hashlib.sha256)

response = requests.post(url, data=jsonData, auth=(apikey, checksum.hexdigest()))
const axios = require("axios");
const cryto = require("crypto");

const url = "https://api.datacue.co/v1/batch/orders";
const apikey = "your-api-key-goes-here";
const apisecret = "your-api-secret-goes-here";

const data = [
  {
    order_id: "o1",
    user_id: "u1",
    cart: [
      {
        product_id: "p1",
        variant_id: "v1",
        quantity: 1,
        unit_price: 24,
        currency: "USD"
      },
      {
        product_id: "p2",
        variant_id: "v2",
        quantity: 9,
        unit_price: 42,
        currency: "USD"
      }
    ],
    timestamp: "2018-04-04 23:29:04Z"
  },
  {
    order_id: "o2",
    user_id: "u1",
    cart: [
      {
        product_id: "p1",
        variant_id: "v1",
        quantity: 1,
        unit_price: 24,
        currency: "USD"
      },
      {
        product_id: "p2",
        variant_id: "v2",
        quantity: 9,
        unit_price: 42,
        currency: "USD"
      }
    ],
    timestamp: "2018-04-04 23:29:04Z"
  }
];

var hash = crypto.createHmac("sha256", apisecret).update(JSON.Stringify(data));

//add to default authentication header
axios.defaults.auth = { username: "API-key", password: hash.digest("hex") };

axios.post(url, data);

Endpoint: POST https://api.datacue.co/v1/batch/orders

Request JSON fields

Array of orders object

The above command returns a 201 response code

Create/Update Users

<!--- backend only event (refer to the Python, PHP or Node tab) -->
<?php

$apikey = "Your-API-Key-goes-here";
$apisecret = "Your-API-secret-goes-here";

$datacue = new \DataCue\Client($apikey, $apisecret, $options, $env);

$userDataList = [
    [
      "user_id" => "u1",
      "email" => "spongebob@bikinibottom.com",
      "title" => "Mr",
      "first_name" => "Spongebob",
      "last_name" => "Squarepants",
      "profile" => [
        "loyalty_plan" => "platinum"
      ],
      "wishlist" => ["p1", "p3", "p4"], //array of product ids
      "email_subscriber" => true,
      "guest_account" => false,
      "timestamp" => "2018-04-04 23:29:04-0300"
    ], [
      "user_id" => "u2",
      "email" => "patrick@bikinibottom.com",
      "title" => "Mr",
      "first_name" => "Patrick",
      "last_name" => "Starfish",
      "profile" => [
        "loyalty_plan" => "gold"
      ],
      "wishlist" => ["p1"], //array of product ids
      "email_subscriber" => true,
      "guest_account" => false,
      "timestamp" => "2018-04-04 23:29:04Z"
  ]
];
$res = $datacue->users->batchCreate($userDataList);

import hashlib
import hmac
import json
import requests

url = "https://api.datacue.co/v1/batch/users"
apikey = "your-api-key-goes-here"
apisecret = "your-api-secret-goes-here"

data = [
  {
    "user_id" : "u1",
    "email" : "spongebob@bikinibottom.com",
    "title" : "Mr",
    "first_name" : "Spongebob",
    "last_name" : "Squarepants",
    "profile" : {
      "loyalty_plan" : "platinum"
    },
    "wishlist" : ["p1", "p3", "p4"], # array of product ids
    "email_subscriber" : True,
    "guest_account" : False,
    "timestamp" : "2018-04-04 23:29:04-0300"
  }, {
    "user_id" : "u2",
    "email" : "patrick@bikinibottom.com",
    "title" : "Mr",
    "first_name" : "Patrick",
    "last_name" : "Starfish",
    "profile" : {
      "loyalty_plan" : "gold"
    },
    "wishlist" : ["p1"], # array of product ids
    "email_subscriber" : True,
    "guest_account" : False,
    "timestamp" : "2018-04-04 23:29:04Z"
  }
]

jsonData = json.dumps(data)
checksum = hmac.new(bytes(apisecret,'utf-8'),
  bytes(jsonData, 'utf-8'),
  hashlib.sha256)

response = requests.post(url, data=jsonData, auth=(apikey, checksum.hexdigest()))
const axios = require("axios");
const cryto = require("crypto");

const url = "https://api.datacue.co/v1/batch/users";
const apikey = "your-api-key-goes-here";
const apisecret = "your-api-secret-goes-here";

const data = [
  {
    user_id: "u1",
    email: "spongebob@bikinibottom.com",
    title: "Mr",
    first_name: "Spongebob",
    last_name: "Squarepants",
    profile: {
      loyalty_plan: "platinum"
    },
    wishlist: ["p1", "p3", "p4"], // array of product ids
    email_subscriber: true,
    guest_account: false,
    timestamp: "2018-04-04 23:29:04-0300"
  },
  {
    user_id: "u2",
    email: "patrick@bikinibottom.com",
    title: "Mr",
    first_name: "Patrick",
    last_name: "Starfish",
    profile: {
      loyalty_plan: "gold"
    },
    wishlist: ["p1"], // array of product ids
    email_subscriber: true,
    guest_account: false,
    timestamp: "2018-04-04 23:29:04Z"
  }
];

var hash = crypto.createHmac("sha256", apisecret).update(JSON.Stringify(data));

//add to default authentication header
axios.defaults.auth = { username: "API-key", password: hash.digest("hex") };

axios.post(url, data);

Endpoint: POST https://api.datacue.co/v1/batch/users

Request JSON fields

Array of users

The above command returns a 201 response code

Delete Multiple Products

<!--- backend only event (refer to the Python, PHP or Node tab) -->
<?php

$apikey = "Your-API-Key-goes-here";
$apisecret = "Your-API-secret-goes-here";

$datacue = new \DataCue\Client($apikey, $apisecret);

// batch delete products
$productAndVariantIdList = [
    [
        "product_id" => "p1",
        "variant_id" => "v1",
    ], [
        "product_id" => "p2",
        "variant_id" => "v2",
    ]
];
$res = $datacue->products->batchDelete($productAndVariantIdList);

import hashlib
import hmac
import json
import requests

url = "https://api.datacue.co/v1/batch/products"
apikey = "your-api-key-goes-here"
apisecret = "your-api-secret-goes-here"

data = [
  {
    "product_id": "p1",
    "variant_id":"v1"
  },
  {
    "product_id": "p2",
    "variant_id":"v1"
  }
]

jsonData = json.dumps(data)
checksum = hmac.new(bytes(apisecret,'utf-8'), bytes(jsonData, 'utf-8'), hashlib.sha256)

response = requests.delete(url, data=jsonData, auth=(apikey, checksum.hexdigest()))
const axios = require("axios");

const url = "https://api.datacue.co/v1/batch/products";
const data = [
  {
    product_id: "p1",
    variant_id: "v1"
  },
  {
    product_id: "p2",
    variant_id: "v1"
  }
];

var hash = crypto.createHmac("sha256", apisecret).update(JSON.Stringify(data));

//add to default authentication header
axios.defaults.auth = { username: apikey, password: hash.digest("hex") };

axios.delete(url, data);

Endpoint: DELETE https://api.datacue.co/v1/batch/products

Delete multiple products within one request. Batch DELETE requests only require an id field as follows.

Request JSON fields

product_id and variant_id

The above command returns a 204 response code

Delete Multiple Categories

<!--- backend only event (refer to the Python, PHP or Node tab) -->
<?php

$apikey = "Your-API-Key-goes-here";
$apisecret = "Your-API-secret-goes-here";

$datacue = new \DataCue\Client($apikey, $apisecret);

// batch delete users
$userIdList = ['c1', 'c2'];
$res = $datacue->categories->batchDelete($categoryIdList);

import hashlib
import hmac
import json
import requests

url = "https://api.datacue.co/v1/batch/categories"
apikey = "your-api-key-goes-here"
apisecret = "your-api-secret-goes-here"

data = [
  {
    "category_id": "c1"
  },
  {
    "category_id": "c2"
  },
  {
    "category_id": "c3"
  }
];

jsonData = json.dumps(data)
checksum = hmac.new(bytes(apisecret,'utf-8'), bytes(jsonData, 'utf-8'), hashlib.sha256)

response = requests.delete(url, data=jsonData, auth=(apikey, checksum.hexdigest()))
const axios = require("axios");

const url = "https://api.datacue.co/v1/batch/categories";

const data = [
  {
    category_id: "c1"
  },
  {
    category_id: "c2"
  },
  {
    category_id: "c3"
  }
];

var hash = crypto.createHmac("sha256", apisecret).update(JSON.Stringify(data));

//add to default authentication header
axios.defaults.auth = { username: apikey, password: hash.digest("hex") };

axios.delete(url, data);

Endpoint: DELETE https://api.datacue.co/v1/batch/categories

Delete multiple categories within one request. Batch DELETE requests only require an id field as follows.

Request JSON fields

category_id

The above command returns a 204 response code

Delete Multiple Users

<!--- backend only event (refer to the Python, PHP or Node tab) -->
<?php

$apikey = "Your-API-Key-goes-here";
$apisecret = "Your-API-secret-goes-here";

$datacue = new \DataCue\Client($apikey, $apisecret);

// batch delete users
$userIdList = ['u1', 'u2'];
$res = $datacue->users->batchDelete($userIdList);

import hashlib
import hmac
import json
import requests

url = "https://api.datacue.co/v1/batch/users"
apikey = "your-api-key-goes-here"
apisecret = "your-api-secret-goes-here"

data = [
  {
    "user_id": "u1"
  },
  {
    "user_id": "u2"
  },
  {
    "user_id": "u3"
  }
]

jsonData = json.dumps(data)
checksum = hmac.new(bytes(apisecret,'utf-8'), bytes(jsonData, 'utf-8'), hashlib.sha256)

response = requests.delete(url, data=jsonData, auth=(apikey, checksum.hexdigest()))
const axios = require("axios");

const url = "https://api.datacue.co/v1/batch/users";

const data = [
  {
    user_id: "u1"
  },
  {
    user_id: "u2"
  },
  {
    user_id: "u3"
  }
];

var hash = crypto.createHmac("sha256", apisecret).update(JSON.Stringify(data));

//add to default authentication header
axios.defaults.auth = { username: apikey, password: hash.digest("hex") };

axios.delete(url, data);

Endpoint: DELETE https://api.datacue.co/v1/batch/users

Delete multiple users within one request. Batch DELETE requests only require an id field as follows.

Request JSON fields

user_id

The above command returns a 204 response code

Delete Multiple Orders

<!--- backend only event (refer to the Python, PHP or Node tab) -->
<?php

$apikey = "Your-API-Key-goes-here";
$apisecret = "Your-API-secret-goes-here";

$datacue = new \DataCue\Client($apikey, $apisecret);

$orderIdList = ['o1', 'o2'];
$res = $datacue->orders->batchCancel($orderIdList);

import hashlib
import hmac
import json
import requests

url = "https://api.datacue.co/v1/batch/orders"
apikey = "your-api-key-goes-here"
apisecret = "your-api-secret-goes-here"

data = [
  {
    "order_id": "o1"
  },
  {
    "order_id": "o2"
  }
]

jsonData = json.dumps(data)
checksum = hmac.new(bytes(apisecret,'utf-8'), bytes(jsonData, 'utf-8'), hashlib.sha256)

response = requests.delete(url, data=jsonData, auth=(apikey, checksum.hexdigest()))
const axios = require("axios");

const url = "https://api.datacue.co/v1/batch/orders";

const data = [
  {
    order_id: "o1"
  },
  {
    order_id: "o2"
  }
];

var hash = crypto.createHmac("sha256", apisecret).update(JSON.Stringify(data));

//add to default authentication header
axios.defaults.auth = { username: apikey, password: hash.digest("hex") };

axios.delete(url, data);

Endpoint: DELETE https://api.datacue.co/v1/batch/orders

Delete multiple orders within one request. Batch DELETE requests only require an id field as follows.

Request JSON fields

order_id

The above command returns a 204 response code if successful.

Delete All Products

<!--- backend only event (refer to the Python, PHP or Node tab) -->
<?php

$apikey = "Your-API-Key-goes-here";
$apisecret = "Your-API-secret-goes-here";

$datacue = new \DataCue\Client($apikey, $apisecret);

$res = $this->client->products->deleteAll();

import hashlib
import hmac
import requests

url = "https://api.datacue.co/v1/batch/products/all"
apikey = "your-api-key-goes-here"
apisecret = "your-api-secret-goes-here"

checksum = hmac.new(bytes(apisecret,'utf-8'), bytes("", 'utf-8'), hashlib.sha256)

response = requests.delete(url, auth=(apikey, checksum.hexdigest()))
const axios = require("axios");

const url = "https://api.datacue.co/v1/batch/products/all";

var hash = crypto.createHmac("sha256", apisecret).update("");

//add to default authentication header
axios.defaults.auth = { username: apikey, password: hash.digest("hex") };

axios.delete(url);

Endpoint: DELETE https://api.datacue.co/v1/batch/products/all

Delete ALL products within one request.

Request JSON fields

None

The above command returns a 204 response code

Delete All Categories

<!--- backend only event (refer to the Python, PHP or Node tab) -->
<?php

$apikey = "Your-API-Key-goes-here";
$apisecret = "Your-API-secret-goes-here";

$datacue = new \DataCue\Client($apikey, $apisecret);

// batch delete categories
$res = $datacue->categories->deleteAll();

import hashlib
import hmac
import requests

url = "https://api.datacue.co/v1/batch/categories/all"
apikey = "your-api-key-goes-here"
apisecret = "your-api-secret-goes-here"


checksum = hmac.new(bytes(apisecret,'utf-8'), bytes("", 'utf-8'), hashlib.sha256)

response = requests.delete(url, auth=(apikey, checksum.hexdigest()))
const axios = require("axios");

const url = "https://api.datacue.co/v1/batch/categories/all";

var hash = crypto.createHmac("sha256", apisecret).update("");

//add to default authentication header
axios.defaults.auth = { username: apikey, password: hash.digest("hex") };

axios.delete(url);

Endpoint: DELETE https://api.datacue.co/v1/batch/categories/all

Delete ALL categories within one request.

The above command returns a 204 response code

Delete All Users

<!--- backend only event (refer to the Python, PHP or Node tab) -->
<?php

$apikey = "Your-API-Key-goes-here";
$apisecret = "Your-API-secret-goes-here";

$datacue = new \DataCue\Client($apikey, $apisecret);

// batch delete users
$res = $datacue->users->deleteAll();

import hashlib
import hmac
import requests

url = "https://api.datacue.co/v1/batch/users/all"
apikey = "your-api-key-goes-here"
apisecret = "your-api-secret-goes-here"


checksum = hmac.new(bytes(apisecret,'utf-8'), bytes("", 'utf-8'), hashlib.sha256)

response = requests.delete(url, auth=(apikey, checksum.hexdigest()))
const axios = require("axios");

const url = "https://api.datacue.co/v1/batch/users/all";

var hash = crypto.createHmac("sha256", apisecret).update("");

//add to default authentication header
axios.defaults.auth = { username: apikey, password: hash.digest("hex") };

axios.delete(url);

Endpoint: DELETE https://api.datacue.co/v1/batch/users/all

Delete ALL users within one request.

The above command returns a 204 response code

Delete All Orders

<!--- backend only event (refer to the Python, PHP or Node tab) -->
<?php

$apikey = "Your-API-Key-goes-here";
$apisecret = "Your-API-secret-goes-here";

$datacue = new \DataCue\Client($apikey, $apisecret);

// batch delete orders
$res = $datacue->orders->deleteAll();

import hashlib
import hmac
import requests

url = "https://api.datacue.co/v1/batch/orders/all"
apikey = "your-api-key-goes-here"
apisecret = "your-api-secret-goes-here"


checksum = hmac.new(bytes(apisecret,'utf-8'), bytes("", 'utf-8'), hashlib.sha256)

response = requests.delete(url, auth=(apikey, checksum.hexdigest()))
const axios = require("axios");

const url = "https://api.datacue.co/v1/batch/orders/all";

var hash = crypto.createHmac("sha256", apisecret).update("");

//add to default authentication header
axios.defaults.auth = { username: apikey, password: hash.digest("hex") };

axios.delete(url);

Endpoint: DELETE https://api.datacue.co/v1/batch/orders/all

Delete ALL orders within one request.

The above command returns a 204 response code

Errors

The API returns 3 types of error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid. With a payload that has a descriptive error message. We're always trying to improve so let us know if you encounter any issues interpreting the error message.
401 Unauthorized -- Specified the wrong API key or API secret. Incorrectly formatted authorization header. Specifying an API secret in an endpoint that only requires an API key
500 Internal Server Error -- We had a problem with our server. Try again later.