Handle absence without guessing

An assistant needs a useful answer when nothing clears its quality bar. Merchant resolution and code availability are separate outcomes. An empty code list may still include an activation link and a cashback offer; inspect those fields separately.

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

search items[0].id: null: The merchant did not resolve. Ask for a better name or domain instead of making a codes request with a guessed ID.
codes items: []: No code was returned; it does not by itself establish that the merchant is unknown.
suppressed_code_count: A positive count means the probability threshold or result limit removed candidates.
activation_url + cashback: A known merchant can still have an activation link. Cashback is available only when its own field is non-null.

Step 1 / POST /v1/merchants/search

Resolve an unknown domain

A well-formed search can succeed with no matching merchant. Preserve the null result as normal application data.

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":"unknown","type":"domain","value":"openstock-no-such-store.invalid"}]}'

Request JSON

{
  "queries": [
    {
      "query_id": "unknown",
      "type": "domain",
      "value": "openstock-no-such-store.invalid"
    }
  ]
}

Illustrative full response

{
  "results": [
    {
      "query_id": "unknown",
      "items": [
        {
          "id": null,
          "name": null,
          "domains": [],
          "popularity_rank": null,
          "estimated_shipping": null
        }
      ]
    }
  ]
}

Step 2 / POST /v1/merchants/codes

Filter public codes by your quality bar

This illustration shows a known merchant whose codes do not clear 0.5. The live response can contain qualifying codes when evidence changes. Do not promise that this request will return either a code or an empty list.

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":"nike","merchant_id":"01g4s4gvb1kdc8kz69cm5q2b4f","idempotency_key":"replace-with-your-filter-session-key","min_probability":0.5,"limit":3}]}'

Request JSON

{
  "queries": [
    {
      "query_id": "nike",
      "merchant_id": "01g4s4gvb1kdc8kz69cm5q2b4f",
      "idempotency_key": "replace-with-your-filter-session-key",
      "min_probability": 0.5,
      "limit": 3
    }
  ]
}

Illustrative full response

{
  "results": [
    {
      "query_id": "nike",
      "cashback": {
        "value_type": "percent",
        "value_amount": 3
      },
      "partnered": false,
      "activation_url": "https://api.openstock.sh/mr/01g4s4gvb1kdc8kz69cm5q2b4f",
      "suppressed_code_count": 3,
      "items": []
    }
  ]
}