--- title: "Charge (Zuweisen) a Coupon to a Cumulus number" url: "https://developer.migros.ch/apis/coupons-3/versions/2b8e9e45-2e72-462e-b3cb-d5019d51e0e3/operations/chargeCouponPublic" --- > Full API specification: https://developer.migros.ch/apis/coupons-3/versions/2b8e9e45-2e72-462e-b3cb-d5019d51e0e3.md # Charge (Zuweisen) a Coupon to a Cumulus number `POST` `/migros/customers/publiccoupons/v3/users/{cumulus}/coupons/{gtin}:charge` Operation ID: `chargeCouponPublic` 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.) ## Path parameters - `cumulus` (string, required) - Cumulus number. - `gtin` (string, required) - GTIN (EAN) of Coupon. Its a string as GTINs often are longer than what integers can represent. ## Query parameters - `costcenter` (integer, optional) - The Migros internal costcenter number (Kostenstelle) to be billed. This is necessary especially for charge and reddeem. - `timestamp` (string, optional) - 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. - `terminal_id` (integer, optional) - Only 'Kassen' must use this field and send the Kassen-Nr/Terminal. All other clients **must** leave this fields blank. - `transaction_id` (string, optional) - Transaktions-Nummer; gruppiert z.B. mehrere ReTi-Calls für denselben Kunden. - `unique_request_id` (string, required) - 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.). - `channel` (integer, required) - 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. - `check_code` (integer, optional) - 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. - `active` (integer, optional) - Status-Angabe für Coupon nach Charge; 0 = verfügbar/nicht aktiviert, 1 = aktiviert. Default-Wert je nach channel. Kassen: weglassen; Andere: bitte angeben. - `quantity` (integer, optional) - Quantity of coupons to assign. By default 1. More than one is not really a use-case. - `from` (string, date, optional) - The date from when on the coupon is valid, in the format YYYY-MM-DD. - `to` (string, date, optional) - The date until when the coupon is valid, in the format YYYY-MM-DD. Bonus coupons usually use end of the month. ## Responses - `204` - Charge successful - `default` - Standard HTTP semantics, no machine-interpretable body. ## OpenAPI definition ```yaml openapi: 3.0.0 info: title: Coupons version: 3.4.0 servers: - description: URL of upstream url: https://api.migros.ch paths: /migros/customers/publiccoupons/v3/users/{cumulus}/coupons/{gtin}:charge: post: description: >- 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.) operationId: chargeCouponPublic parameters: - $ref: "#/components/parameters/cumulus" - $ref: "#/components/parameters/gtin" - $ref: "#/components/parameters/costcenter" - $ref: "#/components/parameters/timestamp" - $ref: "#/components/parameters/terminal_id" - $ref: "#/components/parameters/transaction_id" - $ref: "#/components/parameters/unique_request_id" - $ref: "#/components/parameters/channel" - $ref: "#/components/parameters/check_code" - $ref: "#/components/parameters/active" - $ref: "#/components/parameters/quantity" - $ref: "#/components/parameters/valid_from" - $ref: "#/components/parameters/valid_to" responses: "204": description: Charge successful default: description: Standard HTTP semantics, no machine-interpretable body. summary: Charge (Zuweisen) a Coupon to a Cumulus number tags: - Lekker security: - Kong-Api-Key: [] - Basic-Auth: [] components: parameters: cumulus: description: Cumulus number. example: "2099123456789" in: path name: cumulus required: true schema: maxLength: 13 minLength: 13 pattern: ^\d{13}$ type: string gtin: description: GTIN (EAN) of Coupon. Its a string as GTINs often are longer than what integers can represent. in: path name: gtin required: true schema: pattern: ^\d+$ type: string costcenter: description: The Migros internal costcenter number (Kostenstelle) to be billed. This is necessary especially for charge and reddeem. in: query name: costcenter schema: maximum: 9999999 minimum: 1000000 type: integer timestamp: description: >- 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. example: 2023-08-17T14:03:05 in: query name: timestamp schema: pattern: \d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2} type: string terminal_id: description: |- Only 'Kassen' must use this field and send the Kassen-Nr/Terminal. All other clients **must** leave this fields blank. example: 78 in: query name: terminal_id schema: maximum: 999 type: integer transaction_id: description: Transaktions-Nummer; gruppiert z.B. mehrere ReTi-Calls für denselben Kunden. example: jdfjhamnasdl239msnsds34 in: query name: transaction_id schema: maxLength: 32 minLength: 3 type: string unique_request_id: description: 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.). example: lksdfji3dmcns834la in: query name: unique_request_id required: true schema: maxLength: 32 minLength: 3 type: string channel: description: 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. example: 2 in: query name: channel required: true schema: enum: - 1 - 2 - 3 type: integer check_code: description: 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. in: query name: check_code schema: enum: - 1 - 2 - 3 type: integer active: description: "Status-Angabe für Coupon nach Charge; 0 = verfügbar/nicht aktiviert, 1 = aktiviert. Default-Wert je nach channel. Kassen: weglassen; Andere: bitte angeben." in: query name: active schema: enum: - 0 - 1 type: integer quantity: description: Quantity of coupons to assign. By default 1. More than one is not really a use-case. in: query name: quantity schema: maximum: 99 minimum: 1 type: integer valid_from: description: The date from when on the coupon is valid, in the format YYYY-MM-DD. in: query name: from schema: format: date type: string valid_to: description: The date until when the coupon is valid, in the format YYYY-MM-DD. Bonus coupons usually use end of the month. in: query name: to schema: format: date type: string securitySchemes: Kong-Api-Key: description: Kong key-auth authentication in: header name: X-Api-Key type: apiKey Basic-Auth: description: Kong basic-auth authentication scheme: basic type: http ```