Recommendations

All endpoints require the Authorization: Bearer {access_token} header and return application/json. Build the URLs as {BASE_URL} + the indicated path.

📡 Extraction endpoints

List all recommendations

GET {BASE_URL}/api/v2/shopping-lists/

Returns, paginated, all the recommendations for your organization's domain.

<aside> ℹ️

This endpoint uses pagination with a fixed size of 500 records; the limit parameter does not apply here. Go through the results with page.

</aside>

Recommendations for a commerce

GET {BASE_URL}/api/v2/shopping-lists/{commerceId}/lists/

Path parameter	Description
`commerceId`	Commerce identifier in YOM.

A single recommendation

GET {BASE_URL}/api/v2/shopping-lists/{commerceId}/lists/{id}

Path parameter	Description
`commerceId`	Commerce identifier.
`id`	Shopping list identifier.

⚙️ Query parameters

These apply to the listing endpoints (list all recommendations and recommendations for a commerce):

Parameter	Type	Default	Description
`page`	integer	`1`	Page number.
`limit`	integer	`10`	Records per page. Applies only to the per-commerce endpoint (maximum 100). The domain endpoint uses a fixed size of 500.
`sort`	string	`-updatedAt`	Sort field. Prefix `-` = descending (e.g. `-updatedAt`).
`type`	string	—	Filters by list type (e.g. `recommendation`).
`q`	string	—	Search by name (`name`).
`populate`	boolean	`false`	Enriches the response by resolving commerce and product references.

Example — cURL:

curl "{BASE_URL}/api/v2/shopping-lists/{commerceId}/lists/?limit=100&page=1&sort=-updatedAt" \
  -H "Authorization: Bearer {access_token}"

populate option

Adding ?populate=true enriches the response by resolving references directly. It resolves:

Commerce → external identifier and channel (commerceId.contact.externalId, commerceId.channel).
Product → the sku of each item.

<aside> ℹ️

</aside>