Generate a merchant-backed code

A direct merchant integration can create a single-use code when you request it. The source field makes that capability visible in the response. A generated code still has merchant eligibility rules; preserve the offer description and conditions when presenting it.

Response examples are illustrative unless labelled as a synthetic fixture. They preserve the API envelope but do not represent current availability, measured performance or checkout verification. Example codes cannot be redeemed; example links omit live attribution. Use the URLs returned by your real request.

What to inspect

source: generated identifies a code created through the merchant integration. Inspect this field on each offer.
single_use: A single-use code can be redeemed once. Repeating the same idempotent request does not create a second redemption.
conditions + description: Keep minimum spend, product, customer and subscription restrictions visible. An empty conditions array does not prove a cart is eligible.
cashback + activation_url: Cashback is separate from the code. Use the actual returned link and applicable offer terms.

Step 1 / POST /v1/merchants/search

Resolve the exact merchant domain

Domain matching resolves a known merchant without choosing among similar names. Pass the returned id into the next request.

Set OPENSTOCK_API_KEY in your environment before running this request.

cURL request

curl -sS -X POST 'https://api.openstock.sh/v1/merchants/search' \
  -H "Authorization: Bearer $OPENSTOCK_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"queries":[{"query_id":"brooklinen","type":"domain","value":"brooklinen.com"}]}'

Request JSON

{
  "queries": [
    {
      "query_id": "brooklinen",
      "type": "domain",
      "value": "brooklinen.com"
    }
  ]
}

Illustrative full response

{
  "results": [
    {
      "query_id": "brooklinen",
      "items": [
        {
          "id": "01g4s5d0h956te86ff90h6xts4",
          "name": "Brooklinen",
          "domains": [
            "brooklinen.com",
            "brooklinen2.myshopify.com",
            "shop.app/checkout/9517126"
          ],
          "popularity_rank": 1710,
          "estimated_shipping": {
            "unit": "days",
            "median": 3,
            "q1": 2,
            "q3": 4,
            "basis": "measured_delivery",
            "sample_size": null
          }
        }
      ]
    }
  ]
}

Step 2 / POST /v1/merchants/codes

Request an offer with the merchant ID

Use the resolved merchant ID. Replace the example idempotency key with a stable, opaque key for this shopper and offer session. Keep it for retries. Terms, cashback and availability in a live response can differ from this illustration.

Set OPENSTOCK_API_KEY in your environment before running this request.

cURL request

curl -sS -X POST 'https://api.openstock.sh/v1/merchants/codes' \
  -H "Authorization: Bearer $OPENSTOCK_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"queries":[{"query_id":"brooklinen","merchant_id":"01g4s5d0h956te86ff90h6xts4","idempotency_key":"replace-with-your-shopper-session-key","limit":1}]}'

Request JSON

{
  "queries": [
    {
      "query_id": "brooklinen",
      "merchant_id": "01g4s5d0h956te86ff90h6xts4",
      "idempotency_key": "replace-with-your-shopper-session-key",
      "limit": 1
    }
  ]
}

Illustrative full response

{
  "results": [
    {
      "query_id": "brooklinen",
      "cashback": {
        "value_type": "percent",
        "value_amount": 3
      },
      "partnered": true,
      "activation_url": "https://api.openstock.sh/mr/01g4s5d0h956te86ff90h6xts4",
      "suppressed_code_count": 0,
      "items": [
        {
          "code": "EXAMPLE-NOT-REDEEMABLE",
          "source": "generated",
          "probability": 1,
          "single_use": true,
          "value_type": "percent",
          "value_amount": 15,
          "currency": null,
          "conditions": [],
          "redirect_url": "https://api.openstock.sh/mr/01g4s5d0h956te86ff90h6xts4?code=EXAMPLE-NOT-REDEEMABLE",
          "expires_at": null,
          "last_success": null,
          "description": "15% off",
          "apply_count": null,
          "success_count": null
        }
      ]
    }
  ]
}