Skip to main content
RichRelevance

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. Algonomy operates off a set of APIs that support many applications and clients concurrently. Algonomy 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 Algonomy 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 Algonomy. 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)

A unique key to authorize a client app on behalf of the partner.

Example: clientSecret=wbhz6c41

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 Personalization Cloud 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: ""

The site URL used to link the product recommendation to the Item Page. We recommend submitting only the portion of the URL that constitutes the path from the domain name, as the domain can be inserted separately and this cuts down on filesize. If you must include the domain, we do recommend omitting the protocol to avoid security warnings on mixed http/https pages.

image_url Required string - default: ""

The site URL used to display the product image in recommendations. We recommend submitting only the portion of the URL that constitutes the path from the domain name, as the domain can be inserted separately and this cuts down on payload size. If you must include the domain, we do recommend omitting the protocol to avoid security warnings on mixed http/https pages.

price Optional number - default: -0.01 or -1 if yen

The price for a product that is used for generating recommendations, price filters, and displaying in onsite recommendations. The price of the product as a real number. Example: 8.99

sale_price Optional number - default: -0.01 or -1 if yen

This is the sale price of the product. Only use this if a product is “on sale” (different than regular pricing). Merchandising rules will use this price if it is set in the feed.

  • If the value of sale_price is a valid value ("0" or "12.35" etc.), then the product is converted into cents and then stored in the catalog as that value. The previous value gets overwritten.
  • If the sale price isn’t set, merchandising rules use the list price instead.
  • If some products have sale prices, and others don’t, leave this field blank for products that don’t have a sale price.
  • To remove or reset a sale price, remove any value from this field. This will store the product sale_price as NULL value.
list_price_min Optional number - default: -0.01 or -1 if yen

Minimum list price. Example: 8.99.

list_price_max Optional  number - default: -0.01 or -1 if yen

Maximum list price. Example: 8.99.

sale_price_min Optional number - default: -0.01 or -1 if yen

Minimum sale price. Example: 8.99.

sale_price_max Optional number - default: -0.01 or -1 if yen

Maximum sale price. Example: 8.99.

brand Optional string - maxLength: 255

The product brand.

start_date Optional date-only

When this content is available to be displayed. If not specified, it's available to be displayed any time. Format: yyyy-mm-dd. Defaults to today.

rating Optional number - default: -1

The rating for this content (specified by client). Usually this is generated by collecting the average of customer ratings/reviews.

num_reviews Optional number - default: 0

The number of reviews available for a product.

{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

Identifier of the category's parent category. This is used to build the category hierarchy which can be used to construct merchandising controls for groups of categories. If no parent, then leave the field empty.

Note: A category cannot have more than one parent category.

name Optional string Name of the category to be displayed in recommendations and in the Personalization Cloud 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

The destination a user is sent to when clicking on a recommendation of a category.

image_url Optional string

The category image URL.

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
  • status
     
  • notes
Required object The current status of the catalog update request.
  • Result of catalog update request. (one of FINISHED, FAILED, NEVER_PROCESSED, JSON_EXCEPTION, GENERIC_EXCEPTION)
  • Additional notes to explain the status
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

  • Was this article helpful?