Unified Customer-Item Recommender API

Returns the items with the highest purchase probability-based scores for a customer.

Returns scores based on purchase probabilities for the next seven days from the instant the query is executed.
If a customer has opted out from profiling and/or has no transactions, scores for popular items are returned as a fallback. API consumers are notified about non-personalized scores i.e. popular items via HTTP response header.

get
https://prod-unified-recommender.service.migros.cloud/migros/customers/v1/recommender/customeritempredictions/{domain_id}/{customer_id}

Query Parameters

limitinteger

Number of items. May return less than requested items.

Default:10

>= 1<= 300

newnessstring

Select whether to return only items not bought in the last twelve months, items bought in the last twelve months, or all items.

Allowed values:allnot_boughtbought

Default:all

items_liststring

Comma separated list of up to 50 item IDs. If provided, only items contained in item_list will be returned.

Match pattern:^[a-zA-Z0-9]+(,[a-zA-Z0-9]+){0,49}$

items_blackliststring

Comma separated list of up to 50 item IDs. If provided, items contained in items_blacklist will not be returned.

Match pattern:^[a-zA-Z0-9]+(,[a-zA-Z0-9]+){0,49}$

items_rangestring

Select which items will be scored: all or only currently promoted items.

Allowed values:allpromoted

Default:all

Path Parameters

domain_idstringrequired

Default:Cumulus

customer_idstringrequired

e.g. CumulusID, PersonenID or pseudonymized version thereof

Match pattern:^[a-zA-Z0-9-]+$

Example:2099XXXXXXX

Response

application/json

OK

ItemScores

item_idstring

Migros ArtikelID

Match pattern:^[a-zA-Z0-9=]+$

Example:110136400000

scorenumber(float)

Depending on context, a score relates to a 7-day purchase probability or is just a ranking.

>= 0<= 1

get/migros/customers/v1/recommender/customeritempredictions/{domain_id}/{customer_id}
 
application/json

Returns item statistics for a customer.

Get a customer’s purchased items sorted by recency, frequency, or monetary.

get
https://prod-unified-recommender.service.migros.cloud/migros/customers/v1/recommender/customeritemstatistics/{domain_id}/{customer_id}/{sort_by}

Query Parameters

limitinteger

Number of items

Default:100

>= 1<= 700

num_daysinteger

Number of days to be considered

Default:180

>= 1<= 365

Path Parameters

domain_idstringrequired

Default:Cumulus

customer_idstringrequired

e.g. CumulusID, PersonenID or pseudonymized version thereof

Match pattern:^[a-zA-Z0-9-]+$

Example:2099XXXXXXX

sort_bystringrequired

A comma separated list of sorting criteria. Currently, the following sorting criteria are understood:

  • recency,
  • frequency,
  • monetary.

The ordering is as follows:

  • For recency, the most recent item comes first,
  • For frequency, the item with highest frequency comes first,
  • For monetary, the item with largest revenue comes first.

It is strongly recommended to specify multiple sorting criteria in order to break ties. Example: sort_by=recency,monetary

Match pattern:^(recency|monetary|frequency)(,(recency|monetary|frequency)){0,2}$

Default:recency,monetary

Response

application/json

OK

frequencynumber
item_idstring

Migros ArtikelID

Match pattern:^[a-zA-Z0-9=]+$

Example:110136400000

monetarynumber
recencynumber
get/migros/customers/v1/recommender/customeritemstatistics/{domain_id}/{customer_id}/{sort_by}
 
application/json

Returns the items best matching given ingredients.

Per ingredient, the item Id with the highest number of transactions within the last twelve months is returned, if no customer id is given.
If a customer id is given, and this customer id has purchased any of the items from the ingredient within the last 180 days, the item with the most transactions is returned.
Failures are signaled via the warnings property of the response.

post
https://prod-unified-recommender.service.migros.cloud/migros/customers/v1/recommender/ingredients/{domain_id}

Query Parameters

customer_idstring

e.g. CumulusID, PersonenID or pseudonymized version thereof

Match pattern:^[a-zA-Z0-9-]+$

Example:2099XXXXXXX

include_exclusive_migros_online_productsboolean

Whether or not products only sold by Migros Online should be included in results

Default:false

Path Parameters

domain_idstringrequired

Default:Cumulus

Body

application/json

Ingredient scoring request

ingredientsarray[object]
Show Child Parameters

Response

application/json

OK

dataarray[object]
Show Child Parameters
reference_datestring(date-time)

Example:2022-04-01T00:00:00Z

post/migros/customers/v1/recommender/ingredients/{domain_id}

Body

{}
 
application/json

Returns most relevant currently valid promotions.

Returns an ordered list of current promotions based on relevance for given customer. Relevance score is determined by purchase probabilities.

get
https://prod-unified-recommender.service.migros.cloud/migros/customers/v1/recommender/promotions/{domain_id}

Query Parameters

customer_idstring

e.g. CumulusID, PersonenID or pseudonymized version thereof

Match pattern:^[a-zA-Z0-9-]+$

Default:0

Example:2099XXXXXXX

limitinteger

Number of most relevant promotions to return.

Default:10

>= 1<= 30

Path Parameters

domain_idstringrequired

Default:Cumulus

Response

application/json

OK

PromotionScores

promotion_idstring

Migros AngebotID

Match pattern:^[a-zA-Z0-9=]+$

Example:2010900

scorenumber(float)

Depending on context, a score relates to a 7-day purchase probability or is just a ranking.

>= 0<= 1

get/migros/customers/v1/recommender/promotions/{domain_id}
 
application/json

Returns customers most similar to a list of reference customers.

Similarity in embedding space is measured by angular distance. The returned customers will be the most similar to any (but not necessarily all) of the customers in the reference group.

get
https://prod-unified-recommender.service.migros.cloud/migros/customers/v1/recommender/similarcustomers/{domain_id}/{customer_list}

Query Parameters

limitinteger

Number of most similar customers to return.

Default:10

>= 1<= 100

Path Parameters

domain_idstringrequired

Default:Cumulus

customer_liststringrequired

Comma separated list of customers; at least one customer, at most 20.

Match pattern:^[a-zA-Z0-9-]+(,[a-zA-Z0-9-]+){0,19}$

Example:2099XXXXXXX,2099XXXXXXX

Response

application/json

OK

CustomerScores

customer_idstring

e.g. CumulusID, PersonenID or pseudonymized version thereof

Match pattern:^[a-zA-Z0-9-]+$

Example:2099XXXXXXX

scorenumber(float)

Depending on context, a score relates to a 7-day purchase probability or is just a ranking.

>= 0<= 1

get/migros/customers/v1/recommender/similarcustomers/{domain_id}/{customer_list}
 
application/json