Search
K
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-qual.migros.ch/migros/customers/coupons/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/coupons/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-qual.migros.ch/migros/customers/coupons/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/coupons/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-qual.migros.ch/migros/customers/coupons/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/coupons/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-qual.migros.ch/migros/customers/coupons/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/coupons/v3/users/{cumulus}/matches

Body

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

Statistics about available/activated Coupons and UCBs.

This endpoint returns aggregate summary data of a users Coupons and UCBs.

Note that a single ‘Coupons’ can be attributed to a customer several times in which case the Quantity field is larger than 1. The dirac… fields in the response honour Quantity and count such Coupons multiple times while the coupons… field(s) count Coupon types ignoring their Quantity.

get
https://api-qual.migros.ch/migros/customers/coupons/v3/users/{cumulus}/stats

Path Parameters

cumulusstringrequired

Cumulus number.

Match pattern:^\d{13}$

>= 13 characters<= 13 characters

Example:2099123456789

Response

application/json

Summary data.

Stats

Aggregate statistics about Coupons and UCBs of a user.

couponsActivatedintegerrequired

Number of activated Coupons (ignoring Quantity).

Example:3

diracActiveCountintegerrequired

Total number of activated Coupons (counting Quantity).

Example:4

diracAvailableCountintegerrequired

Number of non-redeem Coupons (ignoring Quantity)

Example:7

ucbActiveSumintegerrequired

Sum of all activated UCBs in CHF

Example:30

ucbAvailableSumintegerrequired

Sum of all non-redeemed UCBs in CHF.

Example:75

get/migros/customers/coupons/v3/users/{cumulus}/stats
 
application/json