Search
K
Coupons

Customer-Data

List of all Coupons attributed to a customer

This endpoint returns the set of all Coupons attributed to a certain customer, identified by the Cumulus number. Coupons can be personalised Coupons (regular and POS-Coupons) as well as unpersonalised Partnercoupons (which are distributed to every Cumulus customer).

Personalised Coupons might be “Preview-Coupons”, i.e. a Coupon that is not yet valid (start date of campaign still in the future). These cannot be activated.

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

Path Parameters

cumulusstringrequired

Cumulus number.

Match pattern:^\d{13}$

>= 13 characters<= 13 characters

Example:2099123456789

Response

application/json

Lists of personalised and unpersonalisdc coupons.

UserCouponCollection

Collection of Coupons attributed to a user (cumulus number). Note that the two arrays contain different types of elements.

activatedarray[object]

Personalized coupon information of a user based on ReTi.

Show Child Parameters
availablearray[object]

Personalized coupon information of a user based on ReTi.

Show Child Parameters
partnerarray[object]required

Represents the coupon information based on MDB+.

Show Child Parameters
previewarray[object]required

Personalized coupon information of a user based on ReTi.

Show Child Parameters
redeemedarray[object]required

Personalized coupon information of a user based on ReTi.

Show Child Parameters
get/migros/customers/coupons/v3/users/{cumulus}/coupons
 
application/json

Fetch a single Coupon attributed to a customer

This endpoint returns a single Coupon attributed to a customer (identified via the Cumulus number). Only personalised Coupons can be requested, i.e. this endpoint doesn’t return Partner-Coupons (these might not have a GTIN).

You probably should not use this endpoint at all: To find the list of Coupons of a user use /migros/customers/coupons/v3/users/{cumulus} which provides all information. (The only conceivable usecase for this endpoint is if you got the GTIN through some side channel.)

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

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

application/json

Lists of personalised and unpersonalisdc coupons.

UserCoupon

Personalized coupon information of a user based on ReTi.

couponobject

Represents the coupon information based on MDB+.

Show Child Parameters
expirystring

Date string when the coupon expires. Note that the format is different from coupon.start_date.

Example:2023-09-01+02:00

idstring

The GTIN (EAN) of the Coupon. ReTi calls this “offerId”.

Example:8888122276132945500263

pos_tr_idstring

unique_request_id as provided during redeem call.

Example:303461600060EF280F0C206267706114

previewboolean

If true then start_date is in the future and this Coupon cannot be activated yet as it is considered a “Preview-Coupon”.

publishedstring

Date string when the coupon begins to be usable. Note that the format is different from coupon.start_date.

Example:2023-06-13+02:00

quantityinteger

A single Coupon can be attributed multiple times to a customer. 0 is omitted.

>= 0<= 99

Example:2

redeemedstring

Datetime string when the coupon was redeemed (or empty).

Example:2024-05-10T10:39:06+02:00

statusinteger

1 = available, 2 = activated, 3 = redeemed.

Allowed values:123

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

Activate a Coupon

Only non-redeem Coupons can be activated. It’s okay to activate an already active Coupon.

Note that no more than 50 Coupons can be in state ‘activated’ for a single Cumulus number. Trying to activate more results in a 409 error.

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}:activate

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 activated

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

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