Recommendation Requests

The Recommendation API returns a list of items using the recommendation policy set on an ad unit. This page covers how to request recommendations, show the returned items, and prepare for empty results and failed requests.

Before you begin

API URL: Check your API URL. Recommendation requests do not require an access token.
Ad unit: Get the ID of an ad unit with recommendations enabled from your A2 contact. Your A2 contact sets the recommendation policy, the number of items, and the impression tracking mode on the ad unit.
Catalog: Register the items to recommend in Product Catalog. catalog_id in the response is the item ID in the catalog.

Build the request

When you need a recommendation list, call POST /app/v0/recommendation/{tagid} from the client (web or app) or your server. Put the ad unit ID in tagid. See Serving Recommendation in the API Reference for the available fields.

curl -i -X POST "<A2_API_URL>/app/v0/recommendation/<ad unit ID>" \
  -H "Content-Type: application/json" \
  -d '{"user": {"id": "user-123"}}'

Field	When to use
`user.id`	The user identifier. Always send the same value for the same user. Without it, the user cannot be assigned to a recommendation experiment, and user-history conditions in the recommendation policy (such as excluding items already seen) do not apply.
`seed_item_id`	The catalog ID of a reference item. Use it with policies that recommend based on a specific item, such as related items on a product detail page.
`filter`	Conditions for excluding items from recommendations. The available conditions depend on the catalog, so check with your A2 contact. Each array can hold up to 100 values.

The number of items is set on the ad unit, not in the request.

Caller	What to do after receiving the response
Client	Show the list with the response items, and send recommendation events with `tracking_token` and each item’s `position`.
Server	Pass the response to the client. Pass each item’s `catalog_id` and `position`, and each list’s `tracking_token`. Even if your rules remove some items or change the order, keep the original response `position`, not the on-screen order.

Handle the response

Recommendation response example

{
  "version": "0.1.0",
  "items": [
    { "catalog_id": "catalog-123", "position": 0, "score": 0.87 },
    { "catalog_id": "catalog-234", "position": 1 }
  ],
  "tracking_token": "<tracking_token>",
  "ext": { "ad_log_tracking_mode": "on_event_tracker" }
}

Field	Description
`items[].catalog_id`	The catalog ID of the recommended item. Look up display information such as the name and image in your service’s product data.
`items[].position`	The zero-based recommendation order. Put it as is in `event_position` of recommendation events.
`items[].score`	The recommendation score. It may be absent depending on the recommendation method.
`tracking_token`	The tracking token of this recommendation result. Put it as is in recommendation events.
`ext.ad_log_tracking_mode`	The impression tracking mode. See Recommendation Event Tracking.

Handle the response as follows.

Response	Handling
HTTP `200` with `items`	Show the items and keep `tracking_token`.
HTTP `200` with empty `items`	Hide the recommendation area or show your service’s default list. There are no recommendation events to send.
Error status or network failure	Show your service’s default list. The response has no `tracking_token`.

Failed requests

Set a maximum time your service waits for recommendations. If that time passes or the request fails, replace it with your service’s default list, and do not show responses that arrive later. With the default settings, A2 returns HTTP 408 for requests it cannot process within one second. Error responses include errorcode and ext.message.

HTTP status	`errorcode`	Cause	What to check
`408`	None	A2 could not process the recommendation within one second with the default settings.	Replace it with your service’s default list. If it repeats, send the time and ad unit ID to your A2 contact.
`400`	`1300`	`tagid` is not a UUID.	Check the ad unit ID in the request path.
`400`	`1304`	An array in `filter` has more than 100 values.	Reduce the number of exclusion values.
`404`	`1301`	The ad unit was not found.	Check that the ad unit ID and the A2 environment match.
`422`	`1302`	Recommendations are not enabled on the ad unit.	Ask your A2 contact to set up recommendations.
`422`	`1303`	The ad unit has no recommendation policy to apply.	Ask your A2 contact to check the recommendation policy.

Error response example

{
  "version": "0.1.0",
  "errorcode": "1302",
  "items": [],
  "ext": { "message": "Recommendation not enabled." }
}

If you request again, the recommendation result and tracking_token may change. Use the values of the response you actually showed in events. With On Recommendation Response (on_ad_response), responses that were not shown are also counted as responses.

Next steps

See Recommendation Event Tracking to send impressions, clicks, and conversions of the recommendations you show.

Getting Started

Ad Integration

Recommendation Integration

Data Integration

Verification and Experiments

Recommendation Requests

Before you begin

Build the request

Handle the response

Failed requests

Next steps

​Before you begin

​Build the request

​Handle the response

​Failed requests

​Next steps

Before you begin

Build the request

Handle the response

Failed requests

Next steps