---
title: "Batch merchant offer codes"
method: POST
path: "/v1/merchants/codes"
tags: ["Merchants"]
---

# Batch merchant offer codes

`POST /v1/merchants/codes`

Retrieve ranked offer codes for a set of merchants. Up to 20 queries per request. Each result contains an `items` array of codes; misses return an empty `items` array. Add an `idempotency_key` to deduplicate requests; we suggest using `sha256(user_email + date)` or similar.

## Request body

- MerchantCodesRequest
  - `queries` MerchantCodesQuery[], required — Batch of codes queries (1–20)
    - `query_id` string, required — Caller-supplied opaque identifier correlated back in results
    - `merchant_id` string, required — Checkmate merchant ID obtained from the search endpoint
    - `idempotency_key` string, required — Deduplication key for this query. We suggest using `sha256(user_email + date)` or similar.

## Response `200`

Per-query results. Each result has an `items` array of codes. Misses return an empty `items` array.

- MerchantCodesResponse
  - `results` MerchantCodesResult[], required
    - `query_id` string, required
    - `items` OfferCode[], required — Ranked list of offer codes (minted / static / codeless / partnership / public). Empty array on miss.
      - `code` string, nullable, required — Promo code string, or null for codeless offers
      - `probability` number, required — Estimated probability (0–1) that the code will work at checkout
      - `single_use` boolean, required — True when the code expires after one redemption
      - `value_type` 'percent' | 'fixed' | 'free_shipping' | 'unknown', required — How the discount value is expressed
      - `value_amount` number, nullable, required — Numeric discount amount; semantics depend on value_type (e.g. 10 = 10% or $10)
      - `currency` string, nullable, required — ISO 4217 currency code, present when value_type is "fixed"
      - `conditions` string[], required — Machine-readable condition tags (e.g. minimum_subtotal, product_restricted, applies_on_subscription)
      - `redirect_url` string, nullable, required — Checkmate affiliate-attributed deep-link; null when unavailable
      - `expires_at` number, nullable, required — Unix timestamp (ms) when the code expires, or null when it does not expire
      - `last_success` string, nullable, required — ISO 8601 UTC timestamp of the most recent successful checkout with this code, or null when never observed
      - `description` string, nullable, required — Human-readable description of the offer or null
      - `apply_count` number, nullable, required — Number of times this code has been applied at checkout, or null when not tracked (e.g. campaign/minted codes)
      - `success_count` number, nullable, required — Number of times this code applied successfully (yielded a saving), or null when not tracked (e.g. campaign/minted codes)

## Other responses

- `400` — Invalid request body, missing idempotency_key, or query cap exceeded (max 20)
- `401` — Missing or invalid API key
- `429` — Too many requests. Rate limits are determined on a per partner basis.

---

[API](https://skmtc.dev/openstock/apis/openstock-api.md) · [All operations](https://skmtc.dev/openstock/apis/openstock-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/openstock/openstock-api/revisions/26bc3de53c39/schema)