Merchants

Merchants provide the canonical identity and display name for offer discovery.

• GET /api/v1/omni/merchant returns merchants with at least one live offer for the issuer.
• GET /api/v1/omni/merchant/{merchantId} returns one issuer-scoped merchant by UUID, including a merchant needed for historical reconciliation.

{
  "id": "0df83025-5c37-4bb2-a258-f06bc34fd495",
  "name": "Example Coffee",
  "segmentDefinitions": {
    "new": { "noTransactionsWithinMonths": 12 },
    "lapsed": {
      "transactionsWithinMonths": 12,
      "noTransactionsWithinMonths": 6
    },
    "loyal": { "transactionsWithinMonths": 6 }
  }
}

Segments are evaluated independently for each merchant using that merchant's returned configuration. The defaults are:

• new: no transaction with the merchant in the preceding 12 months.
• lapsed: at least one transaction with the merchant in the preceding 12 months, but none in the preceding 6 months.
• loyal: at least one transaction with the merchant in the preceding 6 months.

Do not hard-code these default windows. Merchants can configure different windows, and the values returned in segmentDefinitions are authoritative for that merchant.

Use id, not name, as the durable key. Names can be corrected and are not guaranteed to be unique outside the authenticated issuer's catalog.

An ID lookup returns 404 when the merchant is not available to the authenticated issuer, even if that UUID exists elsewhere in Percents. This prevents cross-issuer catalog discovery.