---
title: "Unified Customer-Item Recommender API"
url: "https://developer-qual.migros.ch/apis/unified-customer-item-recommender-api-2/versions/06e8ba18-fa54-477e-8cbf-510ade75454a"
---

# Unified Customer-Item Recommender API

OpenAPI specification document.

```json
{"components":{"parameters":{"username":{"in":"path","name":"username","required":true,"schema":{"type":"string"}}},"responses":{"UnauthenticatedError":{"description":"Unauthenticated","headers":{"WWW_Authenticate":{"schema":{"type":"string"}}}}},"schemas":{"ArrayOfUsers":{"items":{"$ref":"#/components/schemas/User"},"type":"array"},"Customer":{"description":"e.g. CumulusID, PersonenID or pseudonymized version thereof","example":"2099XXXXXXX","pattern":"^[a-zA-Z0-9-]+$","type":"string"},"CustomerPromotion":{"default":"0","description":"e.g. CumulusID, PersonenID or pseudonymized version thereof","example":"2099XXXXXXX","pattern":"^[a-zA-Z0-9-]+$","type":"string"},"CustomerScores":{"items":{"properties":{"customer_id":{"$ref":"#/components/schemas/Customer"},"score":{"$ref":"#/components/schemas/Score"}},"type":"object"},"type":"array"},"Embedding":{"description":"Dense vector representing an entity by the entities' statistical properties.","example":[0.7,2.1,-0.8,0.1]},"IncludeMigrosOnlineTransactions":{"default":false,"description":"Whether or not products only sold by Migros Online should be included in results","type":"boolean"},"Item":{"description":"Migros ArtikelID","example":"110136400000","pattern":"^[a-zA-Z0-9=]+$","type":"string"},"ItemScores":{"items":{"properties":{"item_id":{"$ref":"#/components/schemas/Item"},"score":{"$ref":"#/components/schemas/Score"}},"type":"object"},"type":"array"},"Promotion":{"description":"Migros AngebotID","example":"2010900","pattern":"^[a-zA-Z0-9=]+$","type":"string"},"PromotionScores":{"items":{"properties":{"promotion_id":{"$ref":"#/components/schemas/Promotion"},"score":{"$ref":"#/components/schemas/Score"}},"type":"object"},"type":"array"},"ReferenceDate":{"description":"A timestamp representing the upper exclusive limit for the data modeled or returned (i.e., the freshness of the data).","format":"date-time","type":"string"},"Score":{"description":"Depending on context, a score relates to a 7-day purchase probability or is just a ranking.","format":"float","maximum":1,"minimum":0,"type":"number"},"SingleScore":{"example":{"score":0.42},"type":"object"},"User":{"properties":{"auth_role_group":{"type":"string"},"created_at":{"type":"string"},"description":{"type":"string"},"domain_access":{"type":"string"},"email":{"type":"string"},"modified_at":{"type":"string"},"org_group":{"type":"string"},"proxy_user":{"type":"boolean"},"user_id":{"type":"string"},"username":{"type":"string"}},"type":"object"}},"securitySchemes":{"apiKeyAuth":{"in":"header","name":"X-API-Key","type":"apiKey","x-apikeyInfoFunc":"m_recsys.service.key_auth.check_api_key"}}},"info":{"description":"The Unified Customer-Item Recommender API provides probability-based scores and rankings of items & promotions for individual Cumulus customers.\n The API allows to \n * recommend top k relevant items to customers or compute individual customer-item scores.\n * find similar items or similar customers.\n * get vector representations (embeddings) of items and customers.\n\n The Unified Customer-Item Recommender unifies scores for previously-purchased items and not-previously-purchased items (new to the individual customer). It replaces earlier, separate recommenders and their APIs for previously-purchased items (e.g., *UIR*, *Bedarfsrecommender*, *item statistics*) and new items (*WRMF*).\n\n For support, you can reach team Best Match here: ARG_MGB-Ops-Tech-Analytics-BestMatch-Prod-Support@mgb.ch ","title":"Unified Customer-Item Recommender API","version":"2.0.0.dev0"},"openapi":"3.0.1","paths":{"/migros/customers/v1/recommender/customeritemprediction/{domain_id}/{customer_id}/{item_id}":{"get":{"description":"Returns score (purchase probability) for the next seven days from the instant the query is executed. Optionally returns the input features that the model used.","operationId":"m_recsys.service.recommendations_api.get_customer_item_prediction","parameters":[{"in":"path","name":"domain_id","required":true,"schema":{"default":"Cumulus","type":"string"}},{"in":"path","name":"customer_id","required":true,"schema":{"$ref":"#/components/schemas/Customer"}},{"in":"path","name":"item_id","required":true,"schema":{"$ref":"#/components/schemas/Item"}},{"description":"Return features used as input in recommender model.","in":"query","name":"return_features","schema":{"default":false,"type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SingleScore"}}},"description":"OK"},"401":{"description":"Unauthenticated"},"403":{"description":"Forbidden"},"404":{"description":"Unknown domain, customer, or item"}},"security":[{"apiKeyAuth":[]}],"summary":"Returns the purchase probability of an item for a specific customer.","tags":["Online"]}},"/migros/customers/v1/recommender/customeritempredictions/{domain_id}/{customer_id}":{"get":{"description":"Returns scores based on purchase probabilities for the next seven days from the instant the query is executed.\nIf 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.","operationId":"m_recsys.service.recommendations_api.get_customer_item_predictions","parameters":[{"in":"path","name":"domain_id","required":true,"schema":{"default":"Cumulus","type":"string"}},{"in":"path","name":"customer_id","required":true,"schema":{"$ref":"#/components/schemas/Customer"}},{"description":"Number of items. May return less than requested items.","in":"query","name":"limit","schema":{"default":10,"maximum":300,"minimum":1,"type":"integer"}},{"description":"Select whether to return only items not bought in the last twelve months, items bought in the last twelve months, or all items.","in":"query","name":"newness","required":false,"schema":{"default":"all","enum":["all","not_bought","bought"],"type":"string"}},{"description":"Comma separated list of up to 50 item IDs. If provided, only items contained in item_list will be returned.","in":"query","name":"items_list","required":false,"schema":{"pattern":"^[a-zA-Z0-9]+(,[a-zA-Z0-9]+){0,49}$","type":"string"}},{"description":"Comma separated list of up to 50 item IDs. If provided, items contained in items_blacklist will not be returned.","in":"query","name":"items_blacklist","required":false,"schema":{"pattern":"^[a-zA-Z0-9]+(,[a-zA-Z0-9]+){0,49}$","type":"string"}},{"description":"Select which items will be scored: all or only currently promoted items.","in":"query","name":"items_range","required":false,"schema":{"default":"all","enum":["all","promoted"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemScores"}}},"description":"OK"},"401":{"description":"Unauthenticated"},"403":{"description":"Forbidden"},"404":{"description":"Unknown domain or unknown customer"}},"security":[{"apiKeyAuth":[]}],"summary":"Returns the items with the highest purchase probability-based scores for a customer.","tags":["Online"]}},"/migros/customers/v1/recommender/customeritemstatistics/{domain_id}/{customer_id}/{sort_by}":{"get":{"description":"Get a customer's purchased items sorted by recency, frequency, or monetary.","operationId":"m_recsys.service.recommendations_api.get_customer_item_statistics","parameters":[{"in":"path","name":"domain_id","required":true,"schema":{"default":"Cumulus","type":"string"}},{"in":"path","name":"customer_id","required":true,"schema":{"$ref":"#/components/schemas/Customer"}},{"description":"A comma separated list of sorting criteria. Currently, the following sorting criteria are understood:\n * recency,\n * frequency,\n * monetary.\n\nThe ordering is as follows:\n * For *recency*, the most recent item comes first,\n * For *frequency*, the item with highest frequency comes first,\n * For *monetary*, the item with largest revenue comes first.\n\nIt is strongly recommended to specify multiple sorting criteria in order to break ties. Example: sort_by=recency,monetary","in":"path","name":"sort_by","required":true,"schema":{"default":"recency,monetary","pattern":"^(recency|monetary|frequency)(,(recency|monetary|frequency)){0,2}$","type":"string"}},{"description":"Number of items","in":"query","name":"limit","schema":{"default":100,"maximum":700,"minimum":1,"type":"integer"}},{"description":"Number of days to be considered","in":"query","name":"num_days","schema":{"default":180,"maximum":365,"minimum":1,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"items":{"properties":{"frequency":{"type":"number"},"item_id":{"$ref":"#/components/schemas/Item"},"monetary":{"type":"number"},"recency":{"type":"number"}},"type":"object"},"type":"array"}}},"description":"OK"},"401":{"description":"Unauthenticated"},"403":{"description":"Forbidden"},"404":{"description":"Unknown domain or unknown customer"},"422":{"description":"Customer is not a cumulus user"}},"security":[{"apiKeyAuth":[]}],"summary":"Returns item statistics for a customer.","tags":["Online"]}},"/migros/customers/v1/recommender/ingredients/{domain_id}":{"post":{"description":"Per ingredient, the item Id with the highest number of transactions within the last twelve months is returned, if no customer id is given.\nIf 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.\nFailures are signaled via the *warnings* property of the response.","operationId":"m_recsys.service.recommendations_api.post_ingredients","parameters":[{"in":"path","name":"domain_id","required":true,"schema":{"default":"Cumulus","type":"string"}},{"in":"query","name":"customer_id","required":false,"schema":{"$ref":"#/components/schemas/Customer"}},{"description":"Whether or not products only sold by Migros Online should be included in results","in":"query","name":"include_exclusive_migros_online_products","required":false,"schema":{"default":false,"type":"boolean"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"ingredients":{"items":{"properties":{"ingredient_id":{"type":"string"},"item_ids":{"items":{"$ref":"#/components/schemas/Item"},"type":"array"}},"type":"object"},"type":"array"}},"type":"object"}}},"description":"Ingredient scoring request","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"properties":{"ingredient_id":{"type":"string"},"item_id":{"$ref":"#/components/schemas/Item"}},"type":"object"},"type":"array"},"reference_date":{"example":"2022-04-01T00:00:00Z","format":"date-time","type":"string"}},"type":"object"}}},"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Unknown domain, unknown customer, or unknown item"}},"security":[{"apiKeyAuth":[]}],"summary":"Returns the items best matching given ingredients.","tags":["Online"]}},"/migros/customers/v1/recommender/promotions/{domain_id}":{"get":{"description":"Returns an ordered list of current promotions based on relevance for given customer. Relevance score is determined by purchase probabilities.","operationId":"m_recsys.service.recommendations_api.get_relevant_promotions","parameters":[{"in":"path","name":"domain_id","required":true,"schema":{"default":"Cumulus","type":"string"}},{"in":"query","name":"customer_id","required":false,"schema":{"$ref":"#/components/schemas/CustomerPromotion"}},{"description":"Number of most relevant promotions to return.","in":"query","name":"limit","required":false,"schema":{"default":10,"maximum":30,"minimum":1,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromotionScores"}}},"description":"OK"},"401":{"description":"Unauthenticated"},"403":{"description":"Forbidden"},"404":{"description":"Unknown domain or unknown customer"}},"security":[{"apiKeyAuth":[]}],"summary":"Returns most relevant currently valid promotions.","tags":["Online"]}},"/migros/customers/v1/recommender/scoreitemgroup/{domain_id}/{reference_date}":{"put":{"description":"This path requests the computation of scores for all customers known in the domain. Scores are not immediately computed but must be acquired from the Google Storage URI returned. Depending on system load, it can take between a few minutes to several hours before scores are available. Clients must periodically check the returned URI, in order to know if the requested scores are ready for download.\n\nThe format of the scores is parquet.\n\nAfter some period (usually several days) computed scores are garbage collected.","operationId":"m_recsys.service.recommendations_api.put_scoreitemgroup","parameters":[{"in":"path","name":"domain_id","required":true,"schema":{"default":"Cumulus","type":"string"}},{"in":"path","name":"reference_date","required":true,"schema":{"example":"2023-04-02T00:00:00Z","format":"date-time","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"bought_limit":{"default":0.75,"description":"Relative share of scores to keep, descending order (aka. X1FilterRatio). This filter is applied after any filters based on single scores (e.g. max_score).","format":"float","maximum":1,"minimum":0,"type":"number"},"items":{"description":"Item IDs to be scored","example":["100146000000","263480108400","110136400000"],"items":{"$ref":"#/components/schemas/Item"},"type":"array"},"max_score":{"default":0.9,"description":"Inclusive upper predicted purchase probability limit. Useful for not offering items which will be bought also without any incentive or communication.","format":"float","maximum":1,"minimum":0,"type":"number"},"not_bought_ratio":{"default":0.2,"description":"Ratio of scores for not bought (in the last 12 months) items to bought items (aka. X0toX1FilterRatio). This filter is applied after any filters based on single scores (e.g. max_score).","format":"float","minimum":0,"type":"number"}},"type":"object"}}},"description":"Batch scoring request parameters","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"scores_uri":{"example":"gs://mgb-recommender-dev-data/1.0.0/scores/Cumulus/c4f01b13d11d7fd2-20211120T113908.123Z-20210919T000000.000Z/scores","format":"uri","type":"string"}},"type":"object"}}},"description":"Scoring request accepted"},"401":{"description":"Unauthenticated"},"403":{"description":"Forbidden"},"404":{"description":"Unknown domain or unknown items"}},"security":[{"apiKeyAuth":[]}],"summary":"Requests computation of an aggregated score per item group (e.g., a product range) for each customer.","tags":["Batch"]}},"/migros/customers/v1/recommender/similarcustomers/{domain_id}/{customer_list}":{"get":{"description":"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.","operationId":"m_recsys.service.recommendations_api.get_similar_customers_for_customerlist","parameters":[{"in":"path","name":"domain_id","required":true,"schema":{"default":"Cumulus","type":"string"}},{"description":"Comma separated list of customers; at least one customer, at most 20.","in":"path","name":"customer_list","required":true,"schema":{"example":"2099XXXXXXX,2099XXXXXXX","pattern":"^[a-zA-Z0-9-]+(,[a-zA-Z0-9-]+){0,19}$","type":"string"}},{"description":"Number of most similar customers to return.","in":"query","name":"limit","schema":{"default":10,"maximum":100,"minimum":1,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerScores"}}},"description":"OK"},"401":{"description":"Unauthenticated"},"403":{"description":"Forbidden"},"404":{"description":"Unknown domain or unknown customer"}},"security":[{"apiKeyAuth":[]}],"summary":"Returns customers most similar to a list of reference customers.","tags":["Online"]}},"/migros/customers/v1/recommender/similaritems/{domain_id}/{items_list}":{"get":{"description":"Similarity in embedding space is measured by angular distance. The returned items will be the most similar to any (but not necessarily all) of the items in the reference group.","operationId":"m_recsys.service.recommendations_api.get_similar_items_for_itemlist","parameters":[{"in":"path","name":"domain_id","required":true,"schema":{"default":"Cumulus","type":"string"}},{"description":"Comma separated list of items; at least one item, at most 20.","in":"path","name":"items_list","required":true,"schema":{"example":"210121024000,165000600000","pattern":"^[a-zA-Z0-9]+(,[a-zA-Z0-9]+){0,19}$","type":"string"}},{"description":"Number of most similar items to return.","in":"query","name":"limit","schema":{"default":10,"maximum":100,"minimum":1,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemScores"}}},"description":"OK"},"401":{"description":"Unauthenticated"},"403":{"description":"Forbidden"},"404":{"description":"Unknown domain or unknown item"}},"security":[{"apiKeyAuth":[]}],"summary":"Returns items most similar to a list of reference items.","tags":["Online"]}},"/migros/customers/v1/recommender/status/{domain_id}":{"get":{"description":"Returns data freshness.","operationId":"m_recsys.service.recommendations_api.get_status","parameters":[{"in":"path","name":"domain_id","required":true,"schema":{"default":"Cumulus","type":"string"}}],"responses":{"200":{"description":"OK"}},"security":[{"apiKeyAuth":[]}],"summary":"Returns API status.","tags":["Online"]}}},"servers":[{"description":"URL of upstream","url":"https://qual-unified-recommender.service.migros.cloud"}],"tags":[{"description":"Optimized for processing customers-item scores in large batches; latencies of up to several seconds.","name":"Batch"},{"description":"Online scoring of individual customers/items.","name":"Online"}],"x-company":"migros","x-edm-domain":"customers","x-headmatter":{"readable_by":"*"},"x-leanix-id":"65daebd4-d882-4807-bf4f-22af4176cf88"}
```