Prepare data and IDs
The item ID links a Catalog item to user activity logs. Using the product or content IDs from your service as they are lets you connect data without conversion. Item IDs must be unique across the A2 environment and can’t be changed after registration. If several data sources use the same IDs, make them distinct before registering, for example with a per-source prefix. Put the item ID inid and the same value in metadata.id. Use metadata for the product data you need, such as its name, image, and category. For field details, see Create a catalog item in API Reference.
Register and look up items
Register
201 with the registered item. If an item with the same ID exists, it returns 409 and leaves the existing item unchanged. A field in the wrong format returns 422.
Look up
Read a single item to check the stored values.GET /api/manager/catalogs) supports keyword (searches title), category, and source. It returns up to 100 items per page; use page and page_size to page through results. For details, see List items in API Reference.
Detailed specifications for single-item lookup and the batch create, update, and delete APIs are being updated. For now, use the request and response examples on this page.
Apply changes
When your service data changes, reflect it in the Catalog. Changes reach A2 features asynchronously, so they may not appear in results right away.Update
Send only the fields you want to change.metadata, however, is replaced as a whole, so include the attributes you want to keep even when changing only some of them.
DELETE /api/manager/catalogs/{catalog_id}; a successful request returns 204. For details, see Update an item and Delete an item in API Reference.
Changing an ID
An item ID can’t be changed after registration. An item registered under a new ID is treated as a different item, and activity logs accumulated under the old ID aren’t linked to it. Your service code and logs must switch to the new ID as well, so if you need to change an ID, agree on a migration approach with your integration contact first.Batch integration
The batch APIs process up to 1,000 items per request. Each item is handled separately, so the rest are applied even if some fail; the response is HTTP200 with the succeeded items (succeeded) and failed items (failed). If a request has more than 1,000 items or is malformed, the whole request is rejected with 422.
This example creates two items when
1002 is already registered.
Response
failed[].id. Batch update returns results in ID order, not request order, so don’t rely on the order. For batch delete, succeeded contains the deleted item IDs.
failed[].reason is a human-readable message, and no separate error code is currently provided. Its wording can change, so use it only to check why an item failed.
Batch create doesn’t overwrite existing items. For periodic syncs, send only the changed items: new items through batch create and existing items through batch update.
Avoid deleting everything and registering it again. Deleting also removes the feature data extracted from the items, so re-registering doesn’t immediately restore their previous state.
Connect and verify activity data
To use Catalog data for recommendations that reflect user activity, connect it to user activity logs. When you send activity logs such as views, add-to-cart events, and purchases, put the registered item ID incatalogs[].id. To send activity logs, see Record Activity Log in API Reference.
If you use recommendations, use the same item IDs in the recommendation request’s seed_item_id, the response’s items[].catalog_id, and the recommendation event log’s event_items.
Send item IDs as the same string in every request. For example, converting "001001" to a number drops the leading zeros, so it may not match the original item.
After integrating, check the following:
- Read a registered item and confirm that
metadatawas stored as intended. - Confirm that the item IDs in your activity logs are the same strings you registered.