Catalog Update API
The Catalog Update API enables users to send catalog update requests as catalog changes are made. The production catalog does not update immediately or directly. The updates are deployed to the production environment at scheduled times that are based upon how long it takes to build and deploy a client’s catalog model.
Important: Only call parameters that you need. RichRelevance operates off a set of APIs that support many applications and clients concurrently. RichRelevance may update and enhance these APIs at any time.
When initially integrating with the Catalog Update API or testing changes in usage of the Catalog Update API, requests should be made to the Staging Environment's instance of the API. Use the following base URL:
https://staging-gateway.richrelevance.com/catalogupdate/v1
When it comes time to make the requests against the Production Environment, drop the "staging-" from the base URL:
https://gateway.richrelevance.com/catalogupdate/v1
The endpoints that extend off of this URL are:
- {baseUrl}/oauth2/token : To authenticate and successfully call the other endpoints.
- {baseUrl}/products : To create and update products.
- {baseUrl}/categories : To create and update categories.
- {baseUrl}/regions : To create and update regions.
Glossary
overrides: Overrides allow the values of certain properties to be overridden when conditions are met. Currently supported overrides are region and sku for products.
properties: Also known as attributes, these are the key-value pairs that define a product, category, content or region.
language_tag: Also known as a locale, with the format lanuage-TERRITORY (like en-US), these codes are used as part of a region definition and to associate property overrides with a language context.
Security
POST {baseUrl}/oauth2/token
The Catalog Update API uses the OAuth2 Client Credentials Grant Type to allow a client to authenticate. Contact your RichRelevance team to request your OAuth2 credentials, a client_id and client_secret pair. Client_secrets need to be kept secure. They should never be shared, and only ever passed via HTTPS.
Request an authorization bearer token by authenticating using your client credentials. The /oauth2/token endpoint must be called first to get a token that will give access to the other endpoints. Use the client id and secret sent to you by RichRelevance. The response from this API will contain your token, which will be valid until it is manually revoked. The response will be provided as JSON.
On all requests to the product and catalog APIs, pass an "Authorization: bearer MY_TOKEN" header. When the token expires you will need to get a new one using your client id and secret again.
Request Legend
Name | Required or Optional | Description |
---|---|---|
grant_type | Required (string) | The access token type. This is always client_credentials |
client_id | Required (string) | The client's ID |
client_secret | Required (string) |
Good Response
{ "token_type": "bearer", "access_token": "AABBCCDD" }
Error Responses
{ "error_description": "Invalid client authentication", "error": "invalid_client" }
{ "error_description": "Invalid grant_type", "error": "unsupported_grant_type" }
Catalog Updates
Updating Product Properties
Both PUT and PATCH can be used to update products in the catalog.
PUT {baseUrl}/products
PATCH {baseUrl}/products
PUT: Put a collection of new products into the catalog or fully replace products with the matching id in the catalog. Updating a product using PUT will remove omitted properties and overrides from the product or set them to defaults.
PATCH: Update a property or properties of a collection of products. Properties not included will be unchanged. Only include properties that you want updated. To change a product to "not recommendable," only include its ID and recommendable set to false.
Request Legend
Note: All property names are case sensitive.
Name | Required or Optional | Input | Description |
---|---|---|---|
id | Required | string - maxLength: 100 |
The identifier of the product. |
name |
Optional |
string - default: "{id}" - maxLength: 255 | The name of the product as it will be displayed in recommendations on site and in the RichRelevance Dashboard. If the name is not sent when the product is created, the name will default to be the same as the id. |
categories | Optional | array of string | Identifier for the categories that the product belongs to. Each Identifier is limited to 400 characters. If the category does not exist, a category will be created with given id, but it will have no name. |
recommendable | Optional | boolean - default: true | Is this product recommendable? true/false. If recommendable is not sent when the product is created, it will default to true. |
link_url | Required | string - default: "" | |
image_url | Required | string - default: "" | |
price | Optional | number - default: -0.01 or -1 if yen | |
sale_price | Optional | number - default: -0.01 or -1 if yen | |
list_price_min | Optional | number - default: -0.01 or -1 if yen | |
list_price_max | Optional | number - default: -0.01 or -1 if yen | |
sale_price_min | Optional | number - default: -0.01 or -1 if yen | |
sale_price_max | Optional | number - default: -0.01 or -1 if yen | |
brand | Optional | string - maxLength: 255 | |
start_date | Optional | date-only | |
rating | Optional | number - default: -1 | |
num_reviews | Optional | number - default: 0 | |
{property_name} | Optional | array of string |
Any additional arbitrary properties of the product can be included as long as their names do not conflict with the "canonical" properties above or the word "overrides". HTML-entity encode single and double quotes in the names and values. |
Example Request
[ { "id": "123", "name": "Playstation 4", "categories": ["E495", "VG555"], "brand": "Sony", "price": 299.99, "recommendable": true, "image_url": "http://my.cdn.com/path/to/my/image/123.jpg", "link_url": "http://my.domain.com/path/to/my/product/detail/123.html", "start_date": "2016-02-28" }, { "id": "124", "name": "XBox One", "categories": ["E495", "VG555"], "brand": "Microsoft", "price": 249.99, "recommendable": true, "image_url": "http://my.cdn.com/path/to/my/image/124.jpg", "link_url": "http://my.domain.com/path/to/my/product/detail/124.html", "start_date": "2016-07-28", "included_games": ["Destiny", "Final Fantasy XV"] } ]
Updating Product Properties with Region Overrides
In your PUT and PATCH requests to update products you can include region based overrides.
NOTE: At this time we do not support the combination of region overrides and sku overrides on the same catalog.
To include region overrides, your regions must be setup first. See the section below on Updating Region Properties.
Example Request
[ { "id": "123", "name": "Playstation 4", "categories": ["E495", "VG555"], "brand": "Sony", "price": 299.99, "recommendable": true, "image_url": "http://my.cdn.com/path/to/my/image/123.jpg", "link_url": "http://my.domain.com/path/to/my/product/detail/123.html", "start_date": 2016-02-28, "overrides": { "region": { "CA": { "properties": { "in_stock": true } }, "WA": { "properties": { "in_stock": false } } } } }, { "id": "124", "name": "XBox One", "categories": ["E495", "VG555"], "brand": "Microsoft", "price": 249.99, "recommendable": true, "image_url": "http://my.cdn.com/path/to/my/image/124.jpg", "link_url": "http://my.domain.com/path/to/my/product/detail/124.html", "start_date": 2016-07-28, "included_games": ["Destiny", "Final Fantasy XV"], "overrides": { "region": { "CA": { "properties": { "in_stock": true } }, "WA": { "properties": { "in_stock": false } } } } } ]
Request Legend
Name | Required or Optional | Input | Description |
---|---|---|---|
overrides | -- | JSON object | Section of category properties to define contextual overrides of the other properties. |
region | -- | JSON object | Under overrides, defines region based overrides of the other properties. |
{region_id} | -- | JSON object | Under region, each region_id must match the id of one of the predefined regions or it will be ignored. Defines the overrides of properties for a particular region. |
properties | -- | JSON object | Under region_id, defines the property override values. |
in_stock | Required | boolean | If in_stock is false, the item will not be recommended. The product will only be recommended if recommendable is set to true in the base product and in_stock is set to true here in the region override. If recommendable is set to false in the base product, that product will not be recommended no matter what in_stock is set to here. |
price | Optional | number - default: -0.01 or -1 if yen | Price of the product, for the specified region. |
sale_price | Optional | number - default: -0.01 or -1 if yen | Sale price of the product, for the specified region. |
price_description | Optional | string - maxLength 1024 | Explanatory text that could be passed through to the layout, if needed. Example: "Closeout sale" |
margin | Optional | string - maxLength 50 |
IMPORTANT: To include a custom attribute inside a region, it must also be present in the base product. Example:
[ { "id": "123", "name": "Playstation 4", "categories": ["E495", "VG555"], "brand": "Sony", "price": 299.99, "recommendable": true, "image_url": "http://my.cdn.com/path/to/my/image/123.jpg", "link_url": "http://my.domain.com/path/to/my/product/detail/123.html", "start_date": 2016-02-28, "sizes": ["XS","S","M","L","XL"], "overrides": { "region": { "CA": { "properties": { "in_stock": true, "sizes": ["M","L"] } }, "WA": { "properties": { "in_stock": false, "sizes": ["XS","L","XL"] } } } } } ]
Updating Product Properties with SKU Overrides
In your PUT and PATCH requests to update products you can include SKU based overrides. The SKU property overrides is only needed if you’re participating in our program for SKU functionality. In addition to the SKU property overrides, you will need to add SKUs to your instrumentation in order to support this functionality.
NOTE: At this time we do not support the combination of region overrides and sku overrides on the same catalog.
Example Request
[ { "id": "123", "name": "Playstation 4", "categories": ["E495", "VG555"], "brand": "Sony", "price": 299.99, "recommendable": true, "image_url": "http://my.cdn.com/path/to/my/image/123.jpg", "link_url": "http://my.domain.com/path/to/my/product/detail/123.html", "start_date": 2016-02-28, "overrides": { "sku": { "123A": { "properties": { "color": "black" } }, "123B": { "properties": { "color": "red" } } } } }, { "id": "124", "name": "XBox One", "categories": ["E495", "VG555"], "brand": "Microsoft", "price": 249.99, "recommendable": true, "image_url": "http://my.cdn.com/path/to/my/image/124.jpg", "link_url": "http://my.domain.com/path/to/my/product/detail/124.html", "start_date": 2016-07-28, "included_games": ["Destiny", "Final Fantasy XV"], "overrides": { "sku": { "124A": { "properties": { "size": "small", "color": "black" } }, "124B": { "properties": { "size": "large", "color": ["black", "gold"] } } } } } ]
Request Legend
Name | Required or Optional | Input | Description |
---|---|---|---|
overrides | -- | JSON object | Section of category properties to define contextual overrides of the other properties. |
sku | -- | JSON object | Under overrides, defines sku based overrides of the other properties. |
{sku_id} | -- | JSON object | Under sku, the identifier of the sku for this product. Defines the overrides of properties for a particular sku. |
properties | -- | JSON object | Under sku_id, defines the property override values. |
{property_name} | Required | string OR array of strings |
{property_name} is a placeholder for the name of a property to define. The value is the value of that property specific to this SKU. Multiple values are permitted and passed as an array of strings. SKU specific images and link urls should be sent with the property names "image_url" and "link_url". "available" is an optional recommended SKU attribute that signifies if the specific SKU is available for recommendation or for sale. |
SKU Size Types
When you’re considering size preference for a shopper, you need to be able to differentiate between different types of sizes. A single shopper might wear size 8 shoes, size 4 dresses, and size S t-shirts. But if the only information given to the system is the sizes themselves, there may be unnecessary confusion between them.
When the shopper buys a pair of shoes, for example, it’s not enough to record that this shopper is a size 8. You need to know that the shopper is an 8 in shoes because you don’t want to later recommend size 8 dresses to that same shopper.
If you are able to send sizes as unique attributes like shirt_size, hat_size, or us_women_shoe_size for example, no further work is needed; that will be enough to keep this information appropriately separated and unconfused.
If you are not able to do this, then there is a workaround. You can create an attribute called SizeType to differentiate between the different types of sizes represented in your catalog. You then associate this parameter with each product in the SKU feed and can be log it each time a user shows a preference for a size.
Updating Category Properties
Both PUT and PATCH can be used to update categories in the catalog.
PUT {baseUrl}/categories
PATCH {baseUrl}/categories
PUT: Put a collection of new categories into the catalog or fully replace categories with the matching id in the catalog. Updating a category using PUT will remove omitted properties and overrides from the category or set them to defaults.
PATCH: Update a category or categories. Properties not included will be unchanged. Only include properties that you want updated.
Request Legend
Note: All property names are case sensitive.
Name | Required or Optional | Input | Description |
---|---|---|---|
id | Required | string - maxLength 400 |
The identifier of the category. |
parent_id | Optional | string - maxLength 400 | |
name | Optional | string | Name of the category to be displayed in recommendations and in the RichRelevance dashboard. This name should be shopper-friendly, some strategies display category names on your site. HTML Entity encode single and double quotes. |
link_url | Optional | string | |
image_url | Optional | string |
Example Request
[ { "id": "E495", "name": "Electronics" }, { "id": "VG555", "parent_id": "E495", "name": "Video Games" } ]
Updating Category Properties with Language Overrides
In your PUT and PATCH requests to update categories you can include language based overrides. This allows users to see language appropriate names for categories as well as the language appropriate category links or category images if those vary by language.
Example Request
[ { "id": "E495", "name": "Electronics", "link_url": "/Electronics.html", "image_url": "/Electronics.jpg", "overrides": { "language": { "en-US": { "properties": { "name": "Electronics", "link_url": "/en-US/Electronics.html", "image_url": "/en-US/Electronics.jpg" } }, "fr-CA": { "properties": { "name": "Électronique", "link_url": "/fr-CA/Electronics.html", "image_url": "/fr-CA/Electronics.jpg" } } } } }, { "id": "VG555", "parent_id": "E495", "name": "Video Games", "overrides": { ... } } ]
Request Legend
Name | Required or Optional | Input | Description |
---|---|---|---|
overrides | -- | JSON object | Section of category properties to define contextual overrides of the other properties. |
language | -- | JSON object | Under overrides, defines language based overrides of the other properties. |
{language_tag} | -- | JSON object | Under language, each language_tag takes the format language-TERRITORY (like en-US). Defines the overrides of properties for a particular language. |
properties | -- | JSON object | Under language_tag, defines the property override values. |
name | Optional | string | Override value for the category name in the context of the specified language. |
image_url | Optional | string | Override value for the category image url in the context of the specified language. |
link_url | Optional | string | Override value for the category link url in the context of the specified language. |
Updating Region Properties
Both PUT and PATCH can be used to update regions in the catalog.
PUT {baseUrl}/regions
PATCH {baseUrl}/regions
PUT: Put a collection of new regions into the catalog or fully replace regions with the matching id in the catalog. Updating a region using PUT will remove omitted properties and overrides from the region or set them to defaults.
PATCH: Update a region or regions. Properties not included will be unchanged. Only include properties that you want updated. Properties can be removed by setting the value of the property to null.
Note that the payload for regions has a different format than products and categories.
Products and categories (array based):
[ {"id": "myId1", ... other properties ... }, {"id": "myId2", ... other properties ...} ]
Regions (path based):
{ "myId1": { ... other properties ... }, "myId2": { ... other properties ...} }
In a future v2 version of the Catalog Update API, all payloads will have this latter format.
Request Legend
Note: All property names are case sensitive.
Name | Required or Optional | Input | Description |
---|---|---|---|
{your region identifier} | Required | string - maxLength 100 | The identifier of the region. Case sensitive. |
name | Optional | string - maxLength 100 | The name of the region. |
description | Optional | string - maxLength 500 | The description of the region. |
currency_code | Optional | string - maxLength 3 | ISO 4217 Alphabetic Currency Code. |
language_tag | See Definition | string - maxLength 8 |
Not required when the localized product/category feed are NOT used, OR if instrumented requests for recommendations pass the language_tag on the request. If language_tag is not defined in the region feed, it is not possible to map from region_id to language_tag to use localized values from the localized product/category feeds. Locale description consisting of country and language. Examples: en-US, sv-SE, de-DE, etc. This is used for formatting the price as a string with correct punctuation (commas, spaces, periods). This field is limited to eight characters. IMPORTANT: When using this country-language combination, the resulting value should consist of ISO language and country codes separated with a hyphen. Example: en-US, en-GB, en-CA |
price_multiplier | Optional | number - default: 100 |
Number of smaller units of the base currency. Example: one dollar has a 100 cents, so the value for USD will be 100. The Yen is the smallest unit in Japan, so the value for JPY will be 1. Note: Always specify the correct multiplier for a currency. This value will be use to compute pricing information for merchandising rules. You can download a reference file here to assist in determining the correct price multiplier for each currency. The only valid multipliers are powers of ten: 1, 10, 100, 1000, etc. |
price_prefix | Optional | string - maxLength 16 | Text that should go in front of the price for the given currency. Example: "$" |
price_suffix | Optional | string - maxLength 16 | Text that should go after the price for this currency. Example: "CAD" |
Example Request
{ "myRegion1": { "name": "Name of region 1", "description": "Description of region 1", "currency_code": "USD", "language_tag": "en-US", "price_multiplier": 100, "price_prefix": "$", "price_suffix": "" }, "myRegion2": { ... }, ... }
Tip: You can confirm that this region information has been successfully added by opening a new Browse Boosting rule creation screen, choosing Region as the context, and clicking on the dropdown list of eligible regions. If the feed has run correctly, you should see all of the regions you just added, displayed by title.
Catalog Deletes
Products, Categories and Regions can all be deleted.
DELETE {baseUrl}/products
DELETE {baseUrl}/categories
DELETE {baseUrl}/regions (Note: json format for regions differs from products and categories)
Request Legend
Note: All property names are case sensitive.
Name | Required or Optional | Input | Description |
---|---|---|---|
id | Required (product and category) | string - maxLength: 100 for product, 400 for category |
The identifier of the product, category. |
{identifier} | Required (region) | string - maxLength: 100 | The identifier of the region. |
Example Request for Products or Categories
[ {"id": "myProduct1"}, {"id": "myProduct2"}, ... ]
Example Request for Regions
{ "myRegion1": null, "myRegion2": null, ... }
Why the difference between products, categories and regions? Regions was developed after we formalized our standards for what will be the version 2 API. Regions follows these newer standards. For regions there will be fewer changes required when moving to the version 2 API.
Responses to Catalog Update and Delete Requests
Processing the request:
{ "trackingId": "YOUR_TRACKING_ID" }
If your oauth2 token is invalid or expired:
{ "error_description": "The access token is invalid or has expired", "error": "invalid_token" }
If your json is malformed:
{ "code": 500, "details": "{meaningful parsing exception}", "message": "Internal Server Error", "status": "error" }
If your json is missing the id of an element:
{ "code": 400, "details": "{}", "message": "Bad Request", "status": "error" }
Tracking Status
In order to track the status of your PUT or PATCH operation, you need your apiKey in a GET command. There are two options, shown below.
Retrieve status of last 100 tracking ids
GET {baseUrl}/status
Response Legend
Name | Required | Type | Description |
---|---|---|---|
trackingID | Required | string | The tracking id of a catalog update request. |
submitted | Required | datetime | The epoch timestamp that the catalog update request was submitted. |
statusMessage
|
Required | object | The current status of the catalog update request.
|
Example Response
[
{
"trackingId": "YOUR_TRACKING_ID",
"submitted": "2016-02-28T16:41:41.090Z",
"statusMessage": {
"status": "FINISHED",
"notes": "Additional notes to explain status."
}
}
]
Retrieve status for tracking id
GET {baseUrl}/status/{trackingId}
Response Legend
Name | Required | Type | Description |
---|---|---|---|
status | Required | object | Result of catalog update request.(one of FINISHED, FAILED, NEVER_PROCESSED, JSON_EXCEPTION, GENERIC_EXCEPTION) |
notes | Required | string | Additional notes to explain the status |
Example Response
{
"status": "FINISHED",
"notes": "Additional notes to explain status."
}
Appendix
Q: My REST client does not support sending a body in a DELETE request, is there an alternative?
A: Yes. You can do a POST instead with the query param "action=delete" using the same body that you would for a DELETE request. There are POST alternatives for each of the PUT, PATCH and DELETE endpoints.
Mapping:
PUT {baseUrl}/products -> POST {baseUrl}/products?action=replace
PATCH {baseUrl}/products -> POST {baseUrl}/products?action=edit
DELETE {baseUrl}/products -> POST {baseUrl}/products?action=delete
PUT {baseUrl}/categories -> POST {baseUrl}/categories?action=replace
PATCH {baseUrl}/categories -> POST {baseUrl}/categories?action=edit
DELETE {baseUrl}/categories -> POST {baseUrl}/categories?action=delete
PUT {baseUrl}/regions -> POST {baseUrl}/regions?action=replace
PATCH {baseUrl}/regions -> POST {baseUrl}/regions?action=edit
DELETE {baseUrl}/regions -> POST {baseUrl}/regions?action=delete