---
title: "Select Coupons of a customer matching product IDs"
url: "https://developer-qual.migros.ch/apis/coupons-3/versions/b27797a2-ad08-41e0-8429-0f1aeab8826f/operations/matchingCoupons"
---

> Full API specification: https://developer-qual.migros.ch/apis/coupons-3/versions/b27797a2-ad08-41e0-8429-0f1aeab8826f.md

# Select Coupons of a customer matching product IDs

`POST` `/migros/customers/coupons/v3/users/{cumulus}/matches`

Operation ID: `matchingCoupons`

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.

## Path parameters

- `cumulus` (string, required) - Cumulus number.

## Request body (required)

Content types: `application/x-www-form-urlencoded`

## Responses

- `200` - Map of GTINs to coupon and product data
- `default` - Standard HTTP semantics (see above), 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-qual.migros.ch
paths:
  /migros/customers/coupons/v3/users/{cumulus}/matches:
    post:
      description: >-
        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.
      operationId: matchingCoupons
      parameters:
        - $ref: "#/components/parameters/cumulus"
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              properties:
                id:
                  type: string
              required:
                - id
              type: object
        description: Product IDs to check, provided as (multiple) id form parameter(s).
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties:
                  $ref: "#/components/schemas/CouponMatch"
                type: object
          description: Map of GTINs to coupon and product data
        default:
          description: Standard HTTP semantics (see above), no machine-interpretable body.
      summary: Select Coupons of a customer matching product IDs
      tags:
        - Customer-Data
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
  schemas:
    CouponMatch:
      description: Information about a Coupon matching products.
      properties:
        coupon:
          $ref: "#/components/schemas/UserCoupon"
        products:
          $ref: "#/components/schemas/ProductList"
      type: object
    UserCoupon:
      description: Personalized coupon information of a user based on ReTi.
      properties:
        coupon:
          $ref: "#/components/schemas/Coupon"
        expiry:
          description: Date string when the coupon expires. **Note** that the format is
            different from coupon.start_date.
          example: 2023-09-01+02:00
          type: string
        id:
          description: The GTIN (EAN) of the Coupon. ReTi calls this  "offerId".
          example: "8888122276132945500263"
          type: string
        pos_tr_id:
          description: unique_request_id as provided during redeem call.
          example: 303461600060EF280F0C206267706114
          type: string
        preview:
          description: If true then start_date is in the future and this Coupon cannot be
            activated yet as it is considered a "Preview-Coupon".
          type: boolean
        published:
          description: 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
          type: string
        quantity:
          description: A single Coupon can be attributed multiple times to a customer. 0
            is omitted.
          example: 2
          maximum: 99
          minimum: 0
          type: integer
        redeemed:
          description: Datetime string when the coupon was redeemed (or empty).
          example: 2024-05-10T10:39:06+02:00
          type: string
        status:
          description: 1 = available, 2 = activated, 3 = redeemed.
          enum:
            - 1
            - 2
            - 3
          type: integer
      type: object
    ProductList:
      description: List of product IDs matching a couopon.
      example:
        - "280134171000"
        - "121301900000"
      items:
        type: string
      type: array
    Coupon:
      description: Represents the coupon information based on MDB+.
      properties:
        campaign_colors:
          description: Optional special colors for special campaigns
          properties:
            dark:
              example: "#66601C"
              type: string
            light:
              example: "#EDEACD"
              type: string
          required:
            - dark
            - light
          type: object
        campaign_id:
          description: The ID of the campaign, if this coupon is part of a campaign.
          example: e58efb75-2327-4b98-aeb0-1f7d9a2f5f1e
          type: string
        customer_group:
          example: cumulus
          type: string
        digital:
          example: true
          type: boolean
        disclaimer:
          description: 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.
          type: string
        discount_amount:
          example: 5-fach Punkte
          type: string
        discount_amount_value:
          example: "5.0"
          type: string
        discount_type:
          example: mehrfach
          type: string
        distribution_channels:
          $ref: "#/components/schemas/DistributionChannels"
        end_date:
          example: 31.10.2024
          type: string
        fine_print:
          type: string
        gtin:
          description: GTIN (EAN) of Coupon. Some Partnercoupons do not have GTINs.
          example: "8888122276132945500263"
        id:
          description: The ID of the Coupon. This is the same as the M-Promo ID; ReTi and
            MDB+ call this Offer ID".
          example: "1871947"
          type: string
        image:
          $ref: "#/components/schemas/Image"
        image_inactive:
          $ref: "#/components/schemas/Image"
        language:
          example: de
          type: string
        links:
          $ref: "#/components/schemas/CouponLinks"
        matching_products:
          description: >-
            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.
          type: integer
        minimum_purchase:
          example: Mindesteinkauf CHF 14.90
          type: string
        minimum_purchase_value:
          example: 14.9
          format: float
          type: number
        name:
          example: Gesamtes Migros-Supermarkt-Sortiment
          type: string
        name_app:
          example: Gesamtes Migros-Supermarkt-Sortiment
          type: string
        name_web:
          example: Gesamtes Migros-Supermarkt-Sortiment
          type: string
        personal:
          example: true
          type: boolean
        previews:
          items:
            $ref: "#/components/schemas/Image"
          type: array
        promocode:
          description: Optional promotion code for Partnercoupons
          example: SommerSale23
          type: string
        promotion_number:
          example: C-ID 1871947
          type: string
        redeemable_area:
          example: Nur regional einlösbar
          type: string
        redeemable_at:
          example: Einlösbar in allen Migros-Filialen in der Schweiz gegen Vorweisen der
            Cumulus-Karte sowie auf Migros Online.
          type: string
        regions:
          description: List of IDs where this Coupon can be redeemed.
          example:
            - ONLINE_SHOP
            - GMAA
            - GMZH
          items:
            type: string
          type: array
        signet:
          $ref: "#/components/schemas/CouponSignet"
        signet_bonuscoupon:
          $ref: "#/components/schemas/Image"
        signet_inactive:
          $ref: "#/components/schemas/CouponSignet"
        start_date:
          type: string
        stationary_redeemable:
          example: false
          type: boolean
        subtitle:
          example: ""
          type: string
        type_id:
          example: "8"
          type: string
        variant:
          example: Rabattcoupon
          type: string
        whole_assortment:
          description: Indicates whether this Coupon is applicable to all products.
          type: boolean
      required:
        - gtin
        - id
        - language
        - name
      type: object
    DistributionChannels:
      description: The list of distribution channels (Micasa, Do It, SportX ...) this
        coupon is usable in.
      properties:
        channels:
          description: All the distribution channels.
          items:
            properties:
              filter:
                example: bikeworld
                type: string
              filter_id:
                example: "12"
                type: string
              id:
                example: bikeworld
                type: string
              logo:
                $ref: "#/components/schemas/Image"
              logo_inactive:
                $ref: "#/components/schemas/Image"
              logo_master:
                type: boolean
              name:
                example: Bike World
                type: string
            type: object
          type: array
        text:
          example: Einlösbar in allen Migros- und Fachmarkt-Filialen sowie auf Migros
            Online und den Online-Shops der Fachmärkte.
          type: string
      required:
        - channels
      type: object
    Image:
      description: 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
      type: string
    CouponLinks:
      description: Represents the links on a coupon based on MDB+.
      properties:
        note:
          description: Note about link
          example: Im Online-Shop einlösbar
          type: string
        onlineshop:
          description: Link information.
          properties:
            name:
              description: Human readable name of the third-party website (for example SportX,
                micasa, Migipedia).
              example: Onlineshop
              type: string
            type:
              description: Link type
              example: info
              type: string
            url:
              description: URL to a third-party desktop page of the product.
              example: https://www.micasa.ch/
              type: string
          type: object
      type: object
    CouponSignet:
      description: A coupon signet and its properties.
      properties:
        hex_color:
          description: The hexadecimal color code for this signet.
          example: "#003D8C"
          type: string
        logo:
          description: The logo only of the signet
          properties:
            name:
              description: Logo name, useful for example as alt attribute.
              type: string
            vector:
              description: URL of vector image (SVG).
              type: string
          type: object
        stack:
          description: An URL template to a raster/pixel image. Replace the placeholder
            {stack} with an available Rokka stack, e.g "original" to get a
            usable URL.
          example: https://image.migros.ch/coupons/{stack}/ebeaebd5907eeba6a7dab3b1776632f1d3436c81.png
          type: string
        vector:
          description: URL of vector image (SVG).
          example: https://image.migros.ch/coupons/original/be0c000a3088bac1c429d9dd3da16b3081482b7e.svg
          type: string
      type: object
  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
```