OPopenstock
Merchants

Batch merchant offer codes

Changed on

Request merchant-backed and observed offers for up to 20 merchants. Each result includes ranked codes, cashback when available, and an activation link. Read each item’s source, single_use, conditions and description; partnered alone does not establish code availability. A null code is a codeless offer, not a successfully issued coupon. Use min_probability and limit to filter codes; suppressed_code_count reports removed items. Empty items with a non-null activation_url means the store resolved but has no qualifying code. A null activation_url is a miss-shaped result, also returned for an unavailable per-merchant lookup. idempotency_key is required: use an opaque value unique to the partner, shopper/session and merchant, and reuse it when retrying issuance. It deduplicates code issuance; it does not freeze the entire response or extend code validity. wallet_id optionally binds offer and purchase attribution to a user ID within the authenticated partner account. Wallet failures return a per-query error; retry with the same idempotency_key. shopper_name is optional: a first name to carry on the face of a freshly minted code (CHECKMATE-RORY-4O8HHBUN-CN); a replay returns the code already minted.

post/v1/merchants/codes

Request

  • Base URL
    https://api.openstock.sh
  • URL
    https://api.openstock.sh/v1/merchants/codes
  • Auth
    HTTP bearer

Request body

Example request

{
  "queries": [
    {
      "query_id": "q1",
      "merchant_id": "01g4s5d0h956te86ff90h6xts4",
      "idempotency_key": "a3f1e2d4b5c6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2",
      "shopper_name": "Rory",
      "min_probability": 0.5,
      "limit": 3
    }
  ]
}

Response

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

Example response

{
  "results": [
    {
      "query_id": "q1",
      "cashback": {
        "value_type": "percent",
        "value_amount": 3.5
      },
      "partnered": true,
      "activation_url": "https://api.openstock.sh/mr/01g4s5d0h956te86ff90h6xts4?ref=ck_partner_api",
      "suppressed_code_count": 18,
      "items": [
        {
          "code": "EXAMPLE-PUBLIC-CODE",
          "probability": 0.92,
          "source": "observed",
          "value_type": "percent",
          "value_amount": 10,
          "currency": "USD",
          "conditions": [
            "minimum_subtotal"
          ],
          "minimum_subtotal": 175,
          "minimum_subtotal_currency": "USD",
          "redirect_url": "https://api.openstock.sh/mr/01g4s5d0h956te86ff90h6xts4?code=EXAMPLE-PUBLIC-CODE&ref=ck_partner_api",
          "last_success": "2026-06-16T17:00:00.000Z",
          "description": "10% off your first order",
          "apply_count": 1280,
          "success_count": 940,
          "avg_saving_percent": 14.6,
          "avg_saving_amount": 18.2
        }
      ]
    }
  ]
}

Changes

  • cab49329cb6eRevision changes
    • info

      added the new optional request property //

    • info

      added the optional property // to the response with the status

  • e7f321fa7c2fRevision changes
    • info

      added the optional property //// to the response with the status

    • info

      added the optional property //// to the response with the status

    • info

      added the required property //// to the response with the status

    • info

      added the required property //// to the response with the status

    • info

      added the required property //// to the response with the status

    • info

      added the required property //// to the response with the status

    • info

      added the required property //// to the response with the status