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:nameBecause 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.comEuropean data center:
https://dy-api.euCommon 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}/bulkActions
- 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 |
|
| Headers |
|
| Parameters |
|
| Body |
Requests (required, list): List of actions to execute. Each action can be one of the following: Update (object)
Delete
Partial
|
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",
"publish_time": "2018-02-12T17:05:12",
"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 |
|
| Headers |
|
| Parameters |
|
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 limitation / 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.