Creating and Syncing a Product Feed Using APIs – Dynamic Yield Knowledge Base

To enable this capability contact your account manager.

Usually, a product feed is updated periodically. However, if you have a large number of products in your product feed, each update can take some time. To avoid this, you can use an API to update only the changes in your feed (remove a specific item, add a few items, change item properties, and so on), and make changes to the feed more quickly.

Syncing your product catalog via API with Dynamic Yield includes the following steps:

Create the Product Feed in the Dynamic Yield console.
Generate an API Key to include in each API call.
Implement the API calls to send data to Dynamic Yield.

Create the product feed

Go to Assets › Data Feeds and create a new product feed.
For the Feed Source, select Sync via API.
Add any optional properties that will be included in each item of the product feed by clicking New Property. These can later be used for targeting (e.g. if you add "color", you can use it to target users who purchased blue items), affinity score (e.g. include color affinity in the affinity recommendation algorithm), define merchandising rules in your recommendation widgets (e.g. never recommend products with a specific brand).
- Custom property values must be strings, up to 1,000 characters, with no special characters.
- Custom property names must not start with '_id'.
- Once you add a custom property, you cannot remove it. You can stop using it or return empty values, but the property must be in any future items.
To support multiple languages, you can add a property for every translated version of a property you want to include.

Use the format lng:<language code>:<column name> where the language code matches the name you use in the page context.

For example, if your default language is Spanish, and you want to translate the product name to English and German, you would add two properties:
lng:en_EN:name
lng:de_DE:name

Because these properties are optional, blank values will not trigger errors or warnings.

You can create up to 300 properties when working with multiple languages (including all mandatory, custom, and translated columns).
Click Save and Activate to complete the process.

Generate an API key

An API key is used to identify the source of API calls that are sent to Dynamic Yield. You must include the API key in all of the API calls specified in the following section. To enable this feature, speak to your Customer Success Manager.

To generate an API Key:

Go to Settings › API Keys and click New Key.
Specify Feed for the ACL value and click Save.
Copy the value of the key to a secure location.

Creating API calls

The set of APIs include:

Bulk update: Perform multiple API actions in a single call. Update/Insert/Delete one or more items in your feed.
Transaction Status: Get the status of either a specific item or a transaction.

Host URLs

For each API call, use one of the following hosts depending on which Dynamic Yield data center you are connected to.

US data center:

https://dy-api.com

European data center:

https://dy-api.eu

Common parameters

The APIs require you to include information in different parameters. This section describes each parameter, and where to get the required information.

feedId: (string) The ID of the data feed. This is used in most of the APIs. You can get the ID of an existing data feed by going to Assets › Data Feeds and looking in the ID column. If you don't see the ID column, you can add it using the Column dropdown.
itemId: (string) The ID of an item in your data feed. This must match the SKU in the body.
transactionId: (string) The ID of the transaction is included in the response of an API call. It is used in the Transaction Status API.

Bulk update

Use this API to perform multiple API actions in a single call. Each call can include up to 100 update, insert, and delete actions.

Path

/v2/feeds/{feedId}/bulk

Actions

Update: Use to insert a new item into your feed or fully override an existing item.
Delete: Use to delete a single item from your feed.
Partial update: Use to partially update (edit) an existing item in your data feed.

HTTP Method	POST
Headers	DY-API-Key: Your API Key Content-Type: application/json
Parameters	feedId: (string) The ID of the feed
Body	Requests (required, list): List of actions to execute. Each action can be one of the following: Update (object) id (required, string): Item ID action (required, enum): update body (required, object) Data (required, object): sku (required, string): The ID of the item. Must match itemId. group_id (required, string): The group ID of the item url (required, string): Item URL name (required, string): Item display name price (required, number): Item price. Can also be provided as a string. in_stock (required, boolean): Item availability image_url (required, string): Item image URL categories (required, string): Pipe-separated list of categories description (not required, string): A description of the item keywords (not required, string): Pipe-separated list of keywords Used for finding similar products any_other_field (not required, string): Any other field can be inserted with strings values Delete id (required, string) action (required, enum): delete Partial id (required, string) action (required, enum): partial body: Data (required, object): partial item data url (optional, string): Item URL name (optional, string): Item display name price (optional, number): Item price. Can also be provided as a string. in_stock (optional, Boolean): Item availability image_url (optional, string): Item image URL categories (optional, string): Pipe-separated list of categories description (optional, string): A description of the item keywords (optional, string): Pipe-separated list of keywords. Used for finding similar products.

Body example

{
  "requests": [
    {
      "id": "abc-123",
      "action": "update", 
      "body": {
        "data": {
          "sku": "abc-123",
          "group_id": "abc",
          "url": "http://www.example.com/abc-123",
          "name": "white sneakers",
          "price": 29.99,
          "in_stock": true,
          "image_url": "http://www.example.com/abc-123.png",
          "categories": "shoes|sneakers",
          "description": "The white sneakers that everybody wants",
          "keywords": "tag1|tag2",
          "any_other_field": "any other value"
        }
      }
    },
    {
      "id": "abcd-123",
      "action": "delete"
    },
    {
      "id": "abcde-123",
      "action": "partial",
      "body": {
        "data": {
          "price": 39.99
        }
      }
    }
  ]
}

Response example

{
    "success": true,
    "data": {
        "transaction_id": "MDcyNWM0MTEtYWZlZS00MjdkLWExYmYtMDlhMWIwNGFjMzg4LWZpZC0yMTYxNi10cy0xNTg2NjgxOTE0MDYwLXQtcGFydGlhbA=="
    }
}

Transaction status

Use this API to receive the status of an API call.

Path for a specific item

/v2/feeds/{feedId}/transaction/{transactionId}/item/{itemId}

Path for the whole transaction

/v2/feeds/{feedId}/transaction/{transactionId}

HTTP Method	GET
Headers	DY-API-Key: Your API Key
Parameters	feedId: (string) The ID of the feed transactionId: (string) The ID of the transaction received from an API call itemId: (string) The ID of the item

Body example

[
  {
    "item": "sku-1",
    "status": "success",
    "time": "2019-05-11T18:01:21.343+0000"
  },
  {
    "item": "sku-2",
    "status": "success",
    "time": "2019-05-11T18:01:21.497+0000"
  },
  {
    "item": "sku-xxx",
    "status": "success",
    "time": "2019-05-11T18:01:21.422+0000"
  }
]

Test your feed

Send a Bulk Update request as defined in the previous section.
The API call returns in the response a transaction ID called transaction_id. Using this ID, go to the API log and search for the API call status.
In the log, ensure that the API request status is correct (202).

The User Data API logs behave the same as the Experience APIs logs. See the Experience API logs article for more information. In the Product Feed API, the logs display actions (rather than endpoints):

Column	Details
Action	The type of actions in the API call (Delete, Partial, Update)

Troubleshooting response errors

The following are errors that can be returned, and their meanings:

202: request acknowledged
400: error parsing request
401: invalid or missing API key
403: access denied for a valid API key (wrong section, wrong feed ID, illegal operation)
405: wrong HTTP method (not POST, in this case)
422: exceeded feed size or bulk action limit / feed not synced via API / duplicate ID / invalid schema / invalid JSON
429: too many requests received
500: unspecified internal error

Product Feed API status

You can view the product feed health status on the Data Feeds page.

The status is indicated by an icon, and represents the summary of the last 7 days. The date is the last date the status was calculated. View the API log for more details.

Status	Meaning
	Not synced. You have not yet attempted to sync a data feed.
	Synced. Up to 0.5% warnings.
	Synced with warnings. 0.5%-2% warnings.
	Synced with Errors. More than 2% warnings or more than 0.5% errors.

Prerequisites and limitations

If you're changing the sync method from periodic sync to API, your feed must be synced in accordance with the Dynamic Yield schema without a parser function and as a CSV file.
API request limit:
- Up to 600 requests per minute
- Up to 100 actions per batch (using bulk requests)

If you exceed these limits you'll be requested to fix the request rate or you will be removed from the early access program.