Coupons

Charge (Zuweisen) a Coupon to a Cumulus number

Charge assigns an existing coupon to a cumulus number (i.e. buyer). It’s used by the cashier system to assign e.g. the 2x or 5x coupons to a buyer (Cumulus customer). Additionally it’s used by the cashier system to reverse assignments e.g. when charge was done and then to correct this (Storno). It is basically the reverse operation of redeem.

Note: The parameters can be sent as query parameters in the URL or as application/x-www-form-urlencoded in the request body (or any combination, it just doesn’t matter.)

post
https://api.migros.ch/migros/customers/publiccoupons/v3/users/{cumulus}/coupons/{gtin}:charge

Query Parameters

costcenterinteger

The Migros internal costcenter number (Kostenstelle) to be billed. This is necessary especially for charge and reddeem.

>= 1000000<= 9999999

timestampstring

You probably should not send this value at all unless this is some kind of offline request for some internal transaction that happened in the past. It’s whole purpose is for logging and correlating different transactions but this is better done via transaction_id.

Format is Y-m-d\TH:i:s; Default is the time this call arrives at Reti.

Match pattern:\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}

Example:2023-08-17T14:03:05

terminal_idinteger

Only ‘Kassen’ must use this field and send the Kassen-Nr/Terminal.
All other clients must leave this fields blank.

<= 999

Example:78

transaction_idstring

Transaktions-Nummer; gruppiert z.B. mehrere ReTi-Calls für denselben Kunden.

>= 3 characters<= 32 characters

Example:jdfjhamnasdl239msnsds34

unique_request_idstringrequired

Die Unique Request-Id muss innerhalb einer konfigurierten Zeitspanne (aktuell 300s) einmalig für das aktuelle Ereignis sein (z.B. Kauftransaktion X für Kunde Y und Coupon Z). Anhand dieser ID beurteilt ReTi, ob ein Charge bereits erfolgt ist (Offline-Buchungen, Mehrfach-Aufrufe usw.).

>= 3 characters<= 32 characters

Example:lksdfji3dmcns834la

channelintegerrequired

Channel of the coupon; 1 = paper, 2 = digital, 3 = both (e.g. Bonus-Coupon). Usually when making a charge through the M-API you’ll want to use 2.

Allowed values:123

Example:2

check_codeinteger

Coupon type; 1 = transferable, 2 = personal/not transferable, 3 = Earlybird. Bonus coupons are personal. Falls der Checkcode fehlt, wird bei Bonus-Coupons (8888*) check_code==2 angenommen; bei allen anderen werden die vorhandenen Stammdaten berücksichtigt.

Allowed values:123

activeinteger

Status-Angabe für Coupon nach Charge; 0 = verfügbar/nicht aktiviert, 1 = aktiviert. Default-Wert je nach channel. Kassen: weglassen; Andere: bitte angeben.

Allowed values:1

quantityinteger

Quantity of coupons to assign. By default 1. More than one is not really a use-case.

>= 1<= 99

fromstring(date)

The date from when on the coupon is valid, in the format YYYY-MM-DD.

tostring(date)

The date until when the coupon is valid, in the format YYYY-MM-DD. Bonus coupons usually use end of the month.

Path Parameters

cumulusstringrequired

Cumulus number.

Match pattern:^\d{13}$

>= 13 characters<= 13 characters

Example:2099123456789

gtinstringrequired

GTIN (EAN) of Coupon. Its a string as GTINs often are longer than what integers can represent.

Match pattern:^\d+$

Response

Charge successful

post/migros/customers/publiccoupons/v3/users/{cumulus}/coupons/{gtin}:charge
 

Deactivate a Coupon

Only non-redeem Coupons can be deactivated. It’s okay to deactivate an already inactive Coupon.

Note: The parameters can be sent as query parameters in the URL or as application/x-www-form-urlencoded in the request body (or any combination, it just doesn’t matter.)

post
https://api.migros.ch/migros/customers/publiccoupons/v3/users/{cumulus}/coupons/{gtin}:deactivate

Path Parameters

cumulusstringrequired

Cumulus number.

Match pattern:^\d{13}$

>= 13 characters<= 13 characters

Example:2099123456789

gtinstringrequired

GTIN (EAN) of Coupon. Its a string as GTINs often are longer than what integers can represent.

Match pattern:^\d+$

Response

Successfully deactivated

post/migros/customers/publiccoupons/v3/users/{cumulus}/coupons/{gtin}:deactivate
 

Redeem (Einlösen) a Coupon

Redeem a Coupon i.e. use it in a purchase.

Note: The parameters can be sent as query parameters in the URL or as application/x-www-form-urlencoded in the request body (or any combination, it just doesn’t matter.)

post
https://api.migros.ch/migros/customers/publiccoupons/v3/users/{cumulus}/coupons/{gtin}:redeem

Query Parameters

costcenterinteger

The Migros internal costcenter number (Kostenstelle) to be billed. This is necessary especially for charge and reddeem.

>= 1000000<= 9999999

timestampstring

You probably should not send this value at all unless this is some kind of offline request for some internal transaction that happened in the past. It’s whole purpose is for logging and correlating different transactions but this is better done via transaction_id.

Format is Y-m-d\TH:i:s; Default is the time this call arrives at Reti.

Match pattern:\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}

Example:2023-08-17T14:03:05

terminal_idinteger

Only ‘Kassen’ must use this field and send the Kassen-Nr/Terminal.
All other clients must leave this fields blank.

<= 999

Example:78

transaction_idstring

Transaktions-Nummer; gruppiert z.B. mehrere ReTi-Calls für denselben Kunden.

>= 3 characters<= 32 characters

Example:jdfjhamnasdl239msnsds34

unique_request_idstringrequired

Die Unique Request-Id muss innerhalb einer konfigurierten Zeitspanne (aktuell 300s) einmalig für das aktuelle Ereignis sein (z.B. Kauftransaktion X für Kunde Y und Coupon Z). Anhand dieser ID beurteilt ReTi, ob ein Charge bereits erfolgt ist (Offline-Buchungen, Mehrfach-Aufrufe usw.).

>= 3 characters<= 32 characters

Example:lksdfji3dmcns834la

channelintegerrequired

Channel of the coupon; 1 = paper, 2 = digital, 3 = both (e.g. Bonus-Coupon). Usually when making a charge through the M-API you’ll want to use 2.

Allowed values:123

Example:2

check_codeinteger

Coupon type; 1 = transferable, 2 = personal/not transferable, 3 = Earlybird. Bonus coupons are personal. Falls der Checkcode fehlt, wird bei Bonus-Coupons (8888*) check_code==2 angenommen; bei allen anderen werden die vorhandenen Stammdaten berücksichtigt.

Allowed values:123

quantityinteger

Quantity of coupons to assign. By default 1. More than one is not really a use-case.

>= 1<= 99

Path Parameters

cumulusstringrequired

Cumulus number.

Match pattern:^\d{13}$

>= 13 characters<= 13 characters

Example:2099123456789

gtinstringrequired

GTIN (EAN) of Coupon. Its a string as GTINs often are longer than what integers can represent.

Match pattern:^\d+$

Response

Charge successful

post/migros/customers/publiccoupons/v3/users/{cumulus}/coupons/{gtin}:redeem
 

Select Coupons of a customer matching product IDs

This endpoint allows to match a set of Product-IDs against the current Coupons attributed to a customer.

Only Rabattcoupons and Bonuscoupons in the state Available or Activated are matched. Partnercoupons, Preview Coupons and Coupons that have been Redeemed already are not returned.

Like in the other endpoints working with Product IDs this endpoint also operates with the IDs of actual, buyable products as well as the corresponding “Sammler” products.

The response contains a map of Coupon GTINs that are applicable to at least one of the given products. The map entries contain the UserCoupon data, whether this Coupon matches the whole sortiment and the actual IDs matched.

Unlike the product matching endpoints on unpersonalised coupons this endpoint only provides the POST variant.

post
https://api.migros.ch/migros/customers/publiccoupons/v3/users/{cumulus}/matches

Path Parameters

cumulusstringrequired

Cumulus number.

Match pattern:^\d{13}$

>= 13 characters<= 13 characters

Example:2099123456789

Body

application/x-www-form-urlencoded

Product IDs to check, provided as (multiple) id form parameter(s).

idstringrequired

Response

application/json

Map of GTINs to coupon and product data

object
post/migros/customers/publiccoupons/v3/users/{cumulus}/matches

Body

{ "id": "id" }
 
application/json

Coupon

object

Represents the coupon information based on MDB+.

campaign_colorsobject

Optional special colors for special campaigns

Show Child Parameters
campaign_idstring

The ID of the campaign, if this coupon is part of a campaign.

Example:e58efb75-2327-4b98-aeb0-1f7d9a2f5f1e

customer_groupstring

Example:cumulus

digitalboolean

Example:true

disclaimerstring

Terms and conditions.

Example:Ausgenommen sind Gebührensäcke, -marken, Vignetten, Depots, Serviceleistungen, E-Loading, iTunes/App-Karten, SIM-Karten, Gutscheine, Geschenkkarten, Geschenkboxen und alkoholische Getränke. Nur einmalig einlösbar in Verbindung mit der angegebenen Cumulus-Nummer.

discount_amountstring

Example:5-fach Punkte

discount_amount_valuestring

Example:5.0

discount_typestring

Example:mehrfach

distribution_channelsobject

The list of distribution channels (Micasa, Do It, SportX …) this coupon is usable in.

Show Child Parameters
end_datestring

Example:31.10.2024

fine_printstring
gtinrequired

GTIN (EAN) of Coupon. Some Partnercoupons do not have GTINs.

Example:8888122276132945500263

idstringrequired

The ID of the Coupon. This is the same as the M-Promo ID; ReTi and MDB+ call this Offer ID".

Example:1871947

imagestring

An Image URL template. Replace the placeholder {stack} with an available Rokka stack, e.g “original” to get a usable URL.

Example:https://image.migros.ch/coupons/{stack}/5263e8a6f3282b7f411ae5fce947d7acb65db939.png

image_inactivestring

An Image URL template. Replace the placeholder {stack} with an available Rokka stack, e.g “original” to get a usable URL.

Example:https://image.migros.ch/coupons/{stack}/5263e8a6f3282b7f411ae5fce947d7acb65db939.png

languagestringrequired

Example:de

linksobject

Represents the links on a coupon based on MDB+.

Show Child Parameters
matching_productsinteger

Number of products applicable to thos Coupon.
If this number is not know or the Coupon is applicable to all products this field is ommited.

minimum_purchasestring

Example:Mindesteinkauf CHF 14.90

minimum_purchase_valuenumber(float)

Example:14.9

namestringrequired

Example:Gesamtes Migros-Supermarkt-Sortiment

name_appstring

Example:Gesamtes Migros-Supermarkt-Sortiment

name_webstring

Example:Gesamtes Migros-Supermarkt-Sortiment

personalboolean

Example:true

previewsarray[string]

An Image URL template. Replace the placeholder {stack} with an available Rokka stack, e.g “original” to get a usable URL.

Example:https://image.migros.ch/coupons/{stack}/5263e8a6f3282b7f411ae5fce947d7acb65db939.png

promocodestring

Optional promotion code for Partnercoupons

Example:SommerSale23

promotion_numberstring

Example:C-ID 1871947

redeemable_areastring

Example:Nur regional einlösbar

redeemable_atstring

Example:Einlösbar in allen Migros-Filialen in der Schweiz gegen Vorweisen der Cumulus-Karte sowie auf Migros Online.

regionsarray[string]

List of IDs where this Coupon can be redeemed.

Example:ONLINE_SHOP, GMAA, GMZH

signetobject

A coupon signet and its properties.

Show Child Parameters
signet_bonuscouponstring

An Image URL template. Replace the placeholder {stack} with an available Rokka stack, e.g “original” to get a usable URL.

Example:https://image.migros.ch/coupons/{stack}/5263e8a6f3282b7f411ae5fce947d7acb65db939.png

signet_inactiveobject

A coupon signet and its properties.

Show Child Parameters
start_datestring
stationary_redeemableboolean
subtitlestring
type_idstring

Example:8

variantstring

Example:Rabattcoupon

whole_assortmentboolean

Indicates whether this Coupon is applicable to all products.

Example