NAV Navbar
Examples

Overview

This document describes how you can integrate Tagalys with your custom ecommerce store / platform.

Creating your API credentials

{
  "api_server": "https://api-rx.tagalys.com",
  "client_code": "JFJ39R9VJW929DJF",
  "public_api_key": "hdu28fh37f8238idi29djdu38fifjhe8",
  "private_api_key": "j2jdhw9e837chs920dh6cu2hd28dhd2u"
}

Sign up for a Tagalys account at https://next.tagalys.com/signup. For platform, select 'Other'. In the next screen, you will see your API credentials as a JSON object. This includes the following information:

Parameter Description
api_server Protocol and hostname for our API server in your selected region. You should direct all API calls to this origin. In this document we will use https://api-rx.tagalys.com as an example.
client_code The main identifier for your Tagalys account
public_api_key A key that allows access to all our front-end APIs. Only this key should be used in contexts where it may be exposed to your visitors (for example, when making client side API calls directly to Tagalys as is the case when you use our JS plugin).
private_api_key A key that allows access to admin / setup APIs. This allows modifiying your products database, product listing pages etc. It should never be exposed to any untrusted party.

Making API calls

curl -X POST \
  https://api-rx.tagalys.com/v1/endpoint \
  -H 'Content-Type: application/json' \
  -d '"JSON Content"'

The Tagalys API works via POST endpoints that accept data in JSON and FormData formats and responds in JSON format.

Authentication & Identification

{
  "identification": {
    "client_code": "JFJ39R9VJW929DJF",
    "api_key": "j2jdhw9e837chs920dh6cu2hd28dhd2u",
    "store_id": "store_id",
    "currency": "currency_code"
  }
}

The identification key is required for all Tagalys API calls. It should contain the following parameters:

Parameter Description
client_code Client code from your API Credentials. Required for all API calls.
api_key Required for all API calls. Which API key you use will depend on the endpoint you call. Use your private key for Configuration, Product Sync APIs and your public key for all front-end and analytics APIs.
store_id Tagalys supports multi-store setups, and this parameter sets the store context for the call. Required for all API endpoints except Configuration (in which you define your stores and store IDs).
currency Required for all front-end APIs where the default currency is not being used

Configuration API

{
  "identification": {...},
  "stores": [
    {
      "id": "1",
      "label": "English",
      "locale": "en_US",
      "timezone": "America/Los_Angeles",
      "multi_currency_mode": "exchange_rate",
      "products_count": 21532,
      "currencies": [
        // see subsection
      ],
      "fields": [
        // see subsection
      ],
      "tag_sets": [
        // see subsection
      ],
      "sort_options": [
        // see subsection
      ]
    }
  ]
}

Endpoint: /configuration

API Key: Private

This endpoint is used to configure your store(s). It should be called first to define your stores and again if any fields or tag_sets are created. Each call to /configuration should contain the complete definition and not just the delta.

Each Store should contain the following basic fields and associated information as described in the subsections.

Parameter Description
id The ID for the store. This is used in subsequent API calls as identification[store_id].
label Label used when showing this store in the Tagalys Dashboard
locale Two letter language and country codes separated by an underscore. For example, 'en_US'. Number and currency formatting will be based on this field.
timezone Timezone for displaying dates and times in the Tagalys Dashboard.
multi_currency_mode Implementation method for different currencies (currenly, the only value supported is exchange_rate)
products_count Approximate number of products this store contains. This information is used for provisioning resources.

Currencies

[
  {
    "id": "USD",
    "label": "$",
    "fractional_digits": 2,
    "rounding_mode": "round",
    "exchange_rate": 1.0,
    "default": true
  },
  {
    "id": "HKD",
    "label": "HK$",
    "fractional_digits": 2,
    "rounding_mode": "round",
    "exchange_rate": 7.76,
    "default": false
  }
]

This array defines the list of currencies that can be displayed to visitors. Each currency should have the following parameters.

Parameter Description
id The unique identifier for this currency. This is used in subsequent API calls as identification[curency]
label Label used when showing this currency in the Tagalys Dashboard and in front-ends
fractional_digits How many decimal places should be visible when displayed to visitors
rounding_mode The only supported value is round
exchange_rate What multiplier should be used on currency field values defined in products to arrive at a display value for this currency
default Boolean signifying the currency to use when there is no identification[currency] defined in an API call. Only one currency should have this set to true.

Fields & Tag Sets

There are two data structures in Tagalys for storing product data:

Core Fields

Tagalys defines a set of mandatory fields for products. Equivalent fields in your platform should be mapped to these names.

Field name Type Description
__id String The unique identifier for this product that will not change over time
name string
sku string
link string Absolute link to the product detail page
image_url string Absolute link to the product image used in listing pages
image_hover_url string Absolute link to the product hover image used in listing pages
price float The list price of the product in the base currency
sale_price float The selling price of the product in the base currency
introduced_at datetime The date and time (in the format 2016-11-02T09:40:01+00:00) at which the product was first available online. This will be used as the reference value for the 'newness' component of product scores.
in_stock boolean Whether the product is currently in stock
available boolean Whether the product is available to be sold online (for example, via a back-order)
synced_at datetime The date and time (in the format 2016-11-02T09:40:01+00:00) at which the product details were last extracted while syncing to Tagalys

Custom Fields

[
  {
    "name": "inventory",
    "type": "integer",
    "label": "Inventory",
    "display": true
  },
  {
    "name": "caratage",
    "type": "integer",
    "label": "Caratage",
    "display": true,
    "filters": true,
    "display_suffix": "K"
  },
  {
    "name": "short_description",
    "type": "string",
    "label": "Short Description",
    "search": true
  }
]

If you have any product fields (integer, float, datetime, boolean or free text fields) other than the core fields defined above, you should define them in the fields section of the Configuration object. Each field can contain the following parameters.

Parameter Type Required Default Description
name string Yes Machine name of the field. This is used as the key while defining values for products. Should start with a lowercase alphabet, can contain lower case alphabets, numbers and underscores.
type string Yes One of
  • string
  • integer
  • float
  • datetime
  • boolean
label string Yes Human readable name of the field
display boolean No false Should this field be included when product details are requested in front-end APIs?
filters boolean No false Should a front-end filter be created for this field?
search boolean No false Should this field's values be used when searching for products?
currency boolean No false Does this field store currency values? If true, exchange rate logic is applied for the currency in context.

Tag Sets

[
  {
    "id": "categories",
    "label": "Categories",
    "filters": true,
    "search": true
  },
  {
    "id": "color",
    "label": "Color",
    "filters": true,
    "search": true,
    "display": true
  },
  {
    "id": "gender",
    "label": "Gender",
    "filters": true,
    "search": true
  },
  {
    "id": "size",
    "label": "Size",
    "filters": true,
    "search": false,
    "display": true
  }
]

Any product attributes that are predefined strings and can contain one more more values as an array or in a tree structure should be defined as Tag Sets. Tag Set parameters are similar to Custom Fields.

Parameter Type Required Default Description
name string Yes Machine name of the field. Should start with a lowercase alphabet, can contain lower case alphabets, numbers and underscores.
label string Yes Human readable name of the field
display boolean No false Should this tag set be included when product details are requested in front-end APIs?
filters boolean No false Should a front-end filter be created for this tag set?
search boolean No false Should this tag set's values be used when searching for products?

Sort Options

[
  {
    "field": "introduced_at",
    "directions": [
      {
        "direction": "desc",
        "label": "Newest first"
      }
    ]
  },
  {
    "field": "sale_price",
    "directions": [
      {
        "direction": "asc",
        "label": "Price - Low to high"
      },
      {
        "direction": "desc",
        "label": "Price - High to low"
      }
    ]
  }
]

Define the sort options available to visitors on search and product listing pages. Each sort option should contain the following parameters

ParameterDescription
field The ID of the Core or Custom field which is used for sorting
label The label shown to the user if direction labels are not specified
directions An array of directions within this field to allow sorting on. Each direction should contain the following parameters:
Parameter Description
directionOne of asc or desc
labelThe label shown to the user. If blank, the label is taken as the sort option label + (asc) or (desc)

Product Sync APIs

These endpoints are used to keep each store's catalog synced with Tagalys. Once a store has been created, its products should be syced via the sync_feed endpoint and as products are added / edited or deleted, the changes should be sent to the sync_updates endpoint. Both of these endpoints work by receiving a link to a file that contains either the full feed or just the details of the products that have been updated since the last sync.

File Format

{"perform":"index","payload":{"__id":"337","name":"Aviator Sunglasses","sku":"ace000","price":295,"sale_price":249,"link":"http://www.your-store.com/aviator-sunglasses.html","image_url":"http://www.your-store.com/media/catalog/product/a/c/ace000a_1.jpg","image_hover_url":"http://www.your-store.com/media/catalog/product/a/c/ace000a_1_hover.jpg","synced_at":"2016-11-02T09:40:01+00:00","introduced_at":"2013-03-04T16:48:17-08:00","in_stock":true,"description":"Gunmetal frame with crystal gradient polycarbonate lenses in grey. ","short_description":"A timeless accessory staple, the unmistakable teardrop lenses of our Aviator sunglasses appeal to everyone from suits to rock stars to citizens of the world.","__tags":[{"tag_set":{"id":"categories","label":"Categories"},"items":[{"id":"6","label":"Accessories","items":[{"id":"18","label":"Eyewear"}]}]},{"tag_set":{"id":"color","label":"Color"},"items":[{"label":"Silver","id":"15"},{"label":"Grey","id":"16"}]},{"tag_set":{"id":"gender","label":"Gender"},"items":[{"label":"Male","id":"93"}]}]}}
{"perform":"delete","payload":{"__id":"440"}}

For any sync request, a publicly accessible file must be created with jsonl extension and a link to this file must be sent to Tagalys. This is simply a file with one valid json per line.

Each line must contain the following parameters:

Parameter Description
perform Either index (for creating / editing) or delete
payload Details of the product

Constructing the payload

{
  "perform": "index",
  "payload": {
    "__id": "337",
    "name": "Aviator Sunglasses",
    "sku": "ace000",
    "price": 295,
    "sale_price": 249,
    "link": "http://www.your-store.com/aviator-sunglasses.html",
    "image_url": "http://www.your-store.com/media/catalog/product/a/c/ace000a_1.jpg",
    "image_hover_url": "http://www.your-store.com/media/catalog/product/a/c/ace000a_1_hover.jpg",
    "synced_at": "2016-11-02T09:40:01+00:00",
    "introduced_at": "2013-03-04T16:48:17-08:00",
    "in_stock": true,
    "description": "Gunmetal frame with crystal gradient polycarbonate lenses in grey. ",
    "short_description": "A timeless accessory staple, the unmistakable teardrop lenses of our Aviator sunglasses appeal to everyone from suits to rock stars to citizens of the world.",
    "__tags": [
      {
        "tag_set": {
          "id": "categories",
          "label": "Categories"
        },
        "items": [
          {
            "id": "6",
            "label": "Accessories",
            "items": [
              {
                "id": "18",
                "label": "Eyewear"
              }
            ]
          }
        ]
      },
      {
        "tag_set": {
          "id": "color",
          "label": "Color"
        },
        "items": [
          {
            "label": "Silver",
            "id": "15"
          },
          {
            "label": "Grey",
            "id": "16"
          }
        ]
      },
      {
        "tag_set": {
          "id": "gender",
          "label": "Gender"
        },
        "items": [
          {
            "label": "Male",
            "id": "93"
          }
        ]
      }
    ]
  }
}

If perform is delete, the payload only needs to contain the __id parameter.

If perform is index, which is used for creating and editing products, the entire product's details should be present. Fields are entered as keys directly into the payload object. Tag Sets are a complex structure set inside the __tags key.

__tags

The tags object contains two keys: tag_set and items.

tag_set should contain the following parameters:

Parameter Description
id Machine name of the attribute that is used for internal references and in URLs when this tag_set is used as a filter. Can contain lower case alphabets, numbers and underscores. Cannot start with an underscore.
label Name dispalyed to users in the Tagalys Dashboard

items This is an array that can house one more more values for the attribute defined in tag_set. It can also be nested by using the items key within itself. Each item can contain the following parameters:

Parameter Description
id Unique identifier of the item. Can contain lower case alphabets, numbers and underscores. Cannot start with an underscore.
label Name dispalyed to visitors
items For specifying nested attributes like Categories

Sync Feed

{
  "identification": {...},
  "link": "http://www.your-store.com/path/to/feed-file.jsonl?authkey=hdt24628dhw8dg2d6",
  "updates_count": 21532,
  "callback_url": "http://www.yours-store.com/feed-callback"
}

Endpoint: /products/sync_feed

API Key: Private

This endpoint is used to transfer a point-in-time snapshot of the entire product catalog. It is used for the initial product data transfer and at a later point if any updates / deletes have been missed. After this request is processed, any products not in the file are deleted from Tagalys permanently.

Parameters are defined in the Common Sync API parameters section.

Sync Updates

{
  "identification": {...},
  "link": "http://www.your-store.com/path/to/updates-file.jsonl?authkey=hdt24628dhw8dg2d6",
  "updates_count": 7,
  "callback_url": "http://www.yours-store.com/update-callback"
}

Endpoint: /products/sync_updates

API Key: Private

This entpoint is used to transfer updates after the initial sync. If perform is delete, only __id is required. For perform: index, the product's complete data should be present. Partial updates are not supported.

Parameters are defined in the Common Sync API parameters section.

Common Sync API parameters

Both endpoints use the following parameters:

Parameter Description
link A publicly accessible link to the file
updates_count The number of products in the file (and therefore the number of lines in the file)
callback_url Once the sync file is processed, Tagalys will call this URL via POST method with the parameters described below.

Callback parameters

{
  "identification": {...},
  "completed": "http://www.your-store.com/path/to/feed-file.jsonl?authkey=hdt24628dhw8dg2d6"
}

Once a sync file is processed, Tagalys will call the specified Callback URL via POST method with the following parameters.

Parameter Description
identification You should verify your private key to validate this call
completed Link to the file that has been processed

Front End - APIs

Individual Listing Pages

{
  "q": "silver eyewear",
  "qf": {
    "color": ["15"],
    "categories": ["18"]
  }
}

Endpoint: /search

API Key: Public

Parameter Type Required Description
q String Required The search term can be two or more characters
qf Filter Object Optional Optional parameter to include filters implied by the query to get more precise search results. Uses the same format as the f parameter described in the Common listing page parameters section.

In addition to this, all of the parameters in the Common listing page parameters section can be used.

Product Listing Pages

Endpoint: /mpages/:listing-page-name

API Key: Public

Product Listing Pages are created on the Tagalys Dashboard with a name that can be included in the URL. A page's details can be called using the endpoint that includes that page's name.

The request format is as described in the Common listing page parameters section.

Common listing page parameters

{
  "page": 2,
  "per_page": 24,
  "sort": "introduced_at-desc",
  "f": {
    "gender": ["93"],
    "price": {
      "selected_min": 50,
      "selected_max": 100
    }
  },
  "request": [
    "total",
    "results",
    "details",
    "sort_options",
    "filters"
  ]
}

For all listing page APIs (Search and Product Listing Pages), the following parameters can be used.

Parameter Type Required Description
page Integer Optional Requested page number
per_page Integer Optional Number of search results per page
sort String Optional Specify the field and direction to sort results in the format field-direction where direction can be `asc` or `desc`
f String Filter Object

An object with the Tagalys filters selected by the user. The format varies depending on whether the filter is of type checkbox or range.

  • For checkboxes the value is an array of the selected filter IDs
  • For ranges the value is a hash with the following keys:
    • selected_min The starting point of the range selected by the user
    • selected_max The ending point of the range selected by the user
request Array of strings Required

Define what information you want as part of the API response.

  • total The total number of products matching the search / listing page
  • results The product IDs of the matching results
  • details The details of the matching results to enable rendering of the page without making a database call
  • sort_options The available sort options for this list
  • filters The available filters for this list
  • variables (Only for Product Listing Pages) The list of variables defined in the Tagalys Dashboard
  • banners (Only for Product Listing Pages) The list of banners defined in the Tagalys Dashboard

Response format

{
  "total": 164,
  "results": [
    "8810",
    "...",
    "..."
  ],
  "filters": [
    {
      "id": "price",
      "name": "Price",
      "type": "range",
      "min": 29,
      "max": 329
    },
    {
      "id": "gender",
      "name": "Gender",
      "type": "checkbox",
      "items": [
        {
          "id": "female",
          "name": "Female",
          "count": 93,
          "selected": false
        },
        {
          "id": "male",
          "name": "Male",
          "count": 71,
          "selected": false
        }
      ]
    }
  ],
  "sort_options": [
    {
      "id": "trending",
      "label": "Trending",
      "selected": false
    },
    {
      "id": "introduced_at",
      "label": "Introduced at",
      "selected": true,
      "directions": [
        {
          "direction": "desc",
          "label": "What's new",
          "selected": true
        }
      ]
    },
    {
      "id": "price",
      "label": "Price",
      "selected": false,
      "directions": [
        {
          "direction": "asc",
          "label": "Price-low to high",
          "selected": false
        },
        {
          "direction": "desc",
          "label": "Price-high to low",
          "selected": false
        }
      ]
    }
  ],
  "details": [
    {
      "id": "8810",
      "name": "Lorem ipsum dolor sit amet",
      "sku": "LIDSA",
      "link": "https://www.example.com/lorem-ipsum-dolor-sit-amet",
      "image_url": "https://www.example.com/images/lorem-ipsum-dolor-sit-amet.jpg",
      "price": 49,
      "in_stock": true,
    },
    {...},
    {...}
  ]
}

This is the response format of a generic results page that includes filters, sort options, product IDs, and product details. This information can be used to completely render the results page.

List of Listing Pages

You can retrieve a list of listing pages created on Tagalys using this API.

Request

{
  "identification": {...},
  "request": ["url_component", "variables"],
  "per_page": 2,
  "page": 1
}

Response format

{
  "status": "OK",
  "total": 383,
  "results": [
    {
      "name": "Example Page One",
      "url_component": "example-page-one",
      "variables": {
        "page_title": "",
        "description": "",
        "meta_keywords": "",
        "meta_description": ""
      },
      "total": 1158 // products in page
    },
    {
      "name": "Example Page Two",
      "url_component": "example-page-one",
      "variables": {
        "page_title": "",
        "description": "",
        "meta_keywords": "",
        "meta_description": ""
      },
      "total": 246 // products in page
    }
  ]
}

Front End - JavaScript

Tagalys Search suggestions, Search results, Listing pages and Recommendations can be integrated into your front-end using our jQuery plugins.

Include the plugin

<script src="https://d3htxdwqp62ai4.cloudfront.net/tagalys-plugins-v6.js" type="text/javascript"></script>

Include https://d3htxdwqp62ai4.cloudfront.net/tagalys-plugins-v6.js in your footer.

Set the Context

var tagalys_context_opts = {
    api_server: 'https://api-rx.tagalys.com',
    api_identification: {
        client_code: "...",
        api_key: "public-api-key",
        store_id: "...",
        currency: "currency-id" // for use exchange rate transformations to base currency on the API side - should be the id related to the details mentioned in the currency section
    },
    currency: { // currency details for display
        label: '$',
        exchange_rate: 1.0, // to convert from base currency
        fractional_digits: 0,
        locale: "en-US"
    }
};
if(user_id != ""){
    tagalys_context_opts.user_id = user_id;
}
$('body').tagalys_context(tagalys_context_opts);

The Context is set by our jQuery plugin on a DOM element that contains all elements related to Tagalys features. Unless you require multiple Contexts, this element is <body>. The Context specifies the API endpoint with identification details, currency information for the visitor and the visitor's identifying information. Make sure you enter the public API Key and not the private one. These details are accessible by all your visitors.

Search Suggestions

$.fn.tagalys_search_suggestions.search_link = function(q, qf, qin) {
    var search_url_base = 'https://www.your-website.com/';
    if (typeof(qf) == 'undefined' || $.isEmptyObject(qf)) {
        return (search_url_base + '?q=' + encodeURIComponent(q));
    } else {
        qf = Object.keys(qf).map(function(key) {
            return encodeURIComponent(key) + "-" + encodeURIComponent(qf[key]);
        }).join('~');
        return (search_url_base + '?q=' + encodeURIComponent(q) + '&qf=' + qf);
    }
};

Define how links should be constructed using the search_link function. The arguments are:

$('#search').tagalys_search_suggestions({
    currency: {
        label: '$',
        exchange_rate: 1.0,
        fractional_digits: 0,
        locale: "en-US"
    },
    track: 'asynchronous'
});

Finally, initialize the search suggestions plugin. You should define the currency being used by the visitor along with the exchange rate.

Search Results

<div class="tagalys-namespace" id="tagalys-namespace"></div>

<script type="text/javascript">
    $(document).on('tagalys:ready', function() {
        $('#tagalys-namespace').tagalys_search_results({
          per_page: 16,
          pagination_mode: 'pages' // or 'infinite-scroll'
      });
    });
</script>

Create a blank page with your layout and initialize this plugin on an empty DOM element. Make the ID and Class of this element tagalys-namespace to provide sufficient CSS specificity. The plugin will use the URL's q and qf query string parameters to initialize itself. These query string parameters are set by the Search Suggestions plugin.

Product Listing Pages

<div class="tagalys-namespace" id="tagalys-namespace"></div>

<script type="text/javascript">
    $(document).on('tagalys:ready', function() {
        $('#tagalys-namespace').tagalys_mpage({
          name: 'url-slug' // generally part of the page's URL, defined in the Tagalys Dashboard
      });
    });
</script>

Create a blank page with your layout and initialize this plugin on an empty DOM element. Make the ID and Class of this element tagalys-namespace to provide sufficient CSS specificity.

Analytics Integration

Tagalys uses analytics data you send to calculate product scoring and provide you with detailed reports. Once integrated, product scoring is updated automatically, and you can attribute product views / add to carts / buys to specific Tagalys features and even to specific queries / widgets / pages.

We recommend using our JavaScript plugin for analytics tracking. This takes care of setting up and maitaining user identification cookies and handles API communication.

Track User

$.fn.tagalys_analytics.track_user(user_id);

The track_user helper allows you to associate each browsing session with a user account across devices. To perform this association, make the following call after the user logs in. Previous events in the session where the user was not logged in are automatically associated with this user account.

Track Event

$.fn.tagalys_analytics.track_event(event_type, event_data);

Using the track_event helper, you can send Tagalys details on product listing pages and actions. This helps us improve the relevance and sort orders of various Tagalys features, as well as provide you with detailed reports on our dashboard.

event_type maybe one of product_action or product_list.

Product Action Events

product_action events send Tagalys details on each product view, add to cart and buy.

The event_data argument should be an object containing the following parameters:

Parameter Required Description Type Default value
sku Yes The SKU of the target product String NA
action Yes That action that is being performed on the product. One of:
  • view
  • add_to_cart
  • buy
String NA
quantity For add_to_cart and buy The number of items of the sku that are being added to cart or bought Integer NA
order_id For buy The unique ID of the order to which this buy is associated. If an order is placed for multiple items, send the buy event once for each sku with the associated quantity and the same order_id. String NA

Product List Events

product_list events send Tagalys details about searches and product listing pages to enable attribution of product actions to specific features and queries. This helps with providing our popular searches API, sorting products better for individual searches / pages, and with advanced reporting that lets you figure out which pages and searches are working and what can be done to improve conversion.

The event_data argument should be an object containing the following parameters:

Parameter Required Description Type Default value
pl_type Yes The type of the Tagalys feature being shown to the user. One of:
  • search
  • mpage
String NA
pl_details For search and mpage Details of the product list. Can contain the following common details
  • f in the same format as in listing page API requests
and the following pl_type specific details
  • search - The following parameters should be in the same format sent to the search API.
    • q
    • qf
  • mpage
    • url - should match the URL component /m/*url* entered in the Tagalys dashboard for the merchandised page being displayed
    • title - used for displaying the page in Tagalys Dashboard reports
String NA
pl_total Yes The total number of product results for the search / merchandised page Integer NA
pl_page Yes Events should be sent for each page number of the search or merchandised page being displayed. This parameter should mention the page number for the event being sent. Integer NA
pl_sort If not using the default sort option The sort option in the same format as listing page API requests string trending
pl_products Yes An array of SKUs of the products being displayed on the current page. Array of integers NA