{"description":"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.","api_reference":"https://api.openstock.sh/docs","openapi":"https://api.openstock.sh/openapi.json","recipes":[{"id":"generated","title":"Generate a merchant-backed code","summary":"Resolve Brooklinen, request an offer, and inspect its origin and terms.","purpose":"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.","liveDescription":"Open the demo and select Run recipe for a real Brooklinen search and offer request. The response inspector shows the exact requests and returned data.","checks":[{"field":"source","meaning":"generated identifies a code created through the merchant integration. Inspect this field on each offer."},{"field":"single_use","meaning":"A single-use code can be redeemed once. Repeating the same idempotent request does not create a second redemption."},{"field":"conditions + description","meaning":"Keep minimum spend, product, customer and subscription restrictions visible. An empty conditions array does not prove a cart is eligible."},{"field":"cashback + activation_url","meaning":"Cashback is separate from the code. Use the actual returned link and applicable offer terms."}],"steps":[{"title":"Resolve the exact merchant domain","description":"Domain matching resolves a known merchant without choosing among similar names. Pass the returned id into the next request.","method":"POST","path":"/v1/merchants/search","request":{"queries":[{"query_id":"brooklinen","type":"domain","value":"brooklinen.com"}]},"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}}]}]}},{"title":"Request an offer with the merchant ID","description":"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.","method":"POST","path":"/v1/merchants/codes","request":{"queries":[{"query_id":"brooklinen","merchant_id":"01g4s5d0h956te86ff90h6xts4","idempotency_key":"replace-with-your-shopper-session-key","limit":1}]},"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}]}]}}],"url":"https://openstock.sh/recipes/generated","demo_url":"https://openstock.sh/demo?recipe=generated"},{"id":"compare","title":"Compare generated and public codes","summary":"See two offer sources side by side in a single batch.","purpose":"Resolve merchant identity once, then batch offer queries. Source describes where each offer came from; probability describes its reported reliability. A partnership flag is merchant context, so read the source of each item rather than treating every offer at a partnered merchant as generated.","liveDescription":"Open the demo and select Run recipe to compare Brooklinen and Nike using current responses. The demo shows the returned probability for public codes, including low-confidence results; the inspector keeps the full evidence visible.","checks":[{"field":"source","meaning":"generated is created through an integration; merchant_issued is a configured merchant offer; observed is a public code."},{"field":"probability","meaning":"Use the returned score for observed codes. The 0.01 below is an illustrative low-confidence case, not a prediction for your next request."},{"field":"apply_count + success_count","meaning":"Available checkout evidence can be null. The probability uses weighted recent evidence and need not equal the all-time success ratio."},{"field":"query_id","meaning":"Correlate each result with your request; the two merchants remain distinct throughout the batch."}],"steps":[{"title":"Request both sources in one batch","description":"These are known merchant IDs; resolve domains with merchant search in a new integration. No min_probability is set so a low-confidence public code can be inspected. Live results may be empty or have different values.","method":"POST","path":"/v1/merchants/codes","request":{"queries":[{"query_id":"brooklinen","merchant_id":"01g4s5d0h956te86ff90h6xts4","idempotency_key":"replace-with-your-shopper-session-key","limit":1},{"query_id":"nike","merchant_id":"01g4s4gvb1kdc8kz69cm5q2b4f","idempotency_key":"replace-with-your-nike-session-key","limit":1}]},"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}]},{"query_id":"nike","cashback":{"value_type":"percent","value_amount":3},"partnered":false,"activation_url":"https://api.openstock.sh/mr/01g4s4gvb1kdc8kz69cm5q2b4f","suppressed_code_count":0,"items":[{"code":"EXAMPLE-PUBLIC-CODE","source":"observed","probability":0.01,"single_use":false,"value_type":"percent","value_amount":10,"currency":null,"conditions":[],"redirect_url":"https://api.openstock.sh/mr/01g4s4gvb1kdc8kz69cm5q2b4f?code=EXAMPLE-PUBLIC-CODE","expires_at":null,"last_success":null,"description":"10% off","apply_count":12,"success_count":0}]}]}}],"url":"https://openstock.sh/recipes/compare","demo_url":"https://openstock.sh/demo?recipe=compare"},{"id":"shipping","title":"Explain a delivery estimate","summary":"Distinguish merchant delivery data from a network default.","purpose":"Shipping comes from merchant search. Its basis tells an assistant how to qualify the answer. A median is a typical observed or estimated time, not a delivery promise for a particular address or order.","liveDescription":"Open the demo and select Run recipe to inspect current delivery responses for Everlane and AG1. Read the returned basis; data coverage and values can change.","checks":[{"field":"basis: measured_delivery","meaning":"Observed order-to-delivery data for this merchant. Present the median with the interquartile range when available."},{"field":"basis: network_default","meaning":"A general network estimate when merchant delivery data is unavailable. Label it as a network estimate."},{"field":"basis: processing_plus_transit_estimate","meaning":"Merchant processing data plus assumed transit time. This is an estimate rather than observed end-to-end delivery."},{"field":"sample_size","meaning":"Null means the sample count is unavailable; it does not mean zero orders. Null estimated_shipping means no applicable estimate."}],"steps":[{"title":"Read shipping provenance in the search response","description":"These illustrative results show both measured delivery and a default. The catalogue can resolve a merchant even when merchant-specific delivery evidence is unavailable.","method":"POST","path":"/v1/merchants/search","request":{"queries":[{"query_id":"everlane","type":"domain","value":"everlane.com"},{"query_id":"ag1","type":"domain","value":"drinkag1.com"}]},"response":{"results":[{"query_id":"everlane","items":[{"id":"01g4s5dc138qsnh4egsjys8g9c","name":"Everlane","domains":["everlane.com","m34kzg-ke.myshopify.com","shop.app/checkout/62379163734"],"popularity_rank":966,"estimated_shipping":{"unit":"days","median":6,"q1":4,"q3":8,"basis":"measured_delivery","sample_size":null}}]},{"query_id":"ag1","items":[{"id":"01hybscj8sjsxdejx39apgsbv9","name":"AG1","domains":["drinkag1.com"],"popularity_rank":null,"estimated_shipping":{"unit":"days","median":4,"q1":3,"q3":5,"basis":"network_default","sample_size":null}}]}]}}],"url":"https://openstock.sh/recipes/shipping","demo_url":"https://openstock.sh/demo?recipe=shipping"},{"id":"history","title":"Distinguish purchases from visits","summary":"Explore a clearly labelled synthetic shopper with both interaction types.","purpose":"This fixture demonstrates the response shape and assistant presentation. It is synthetic, contains no real shopper data, and does not demonstrate live network coverage. Live history returns available interactions for a shopper you are authorized to look up; hashing an email identifies that shopper but does not grant authorization.","liveLabel":"Open fixture demo","liveDescription":"Select Run recipe in the demo to combine the synthetic history fixture with current merchant and offer responses. The demo labels the two data sources separately.","checks":[{"field":"type: purchased","meaning":"A purchase interaction. Do not infer a product, date, amount or order count: this endpoint returns merchant-level interaction types."},{"field":"type: visited","meaning":"A browsing interaction; never describe it as a purchase."},{"field":"email_sha256","meaning":"SHA-256 of the lowercase, trimmed email. This fixture uses a reserved example identity and is not seeded into live lookup."},{"field":"items: []","meaning":"No returned history. Treat the absence as unavailable context, rather than evidence that the shopper has never bought anything."}],"steps":[{"title":"Fetch the synthetic response fixture","description":"This public fixture requires no API key. It contains two purchase interactions and one visit, and is the same fixture used by the demo.","method":"GET","path":"https://openstock.sh/examples/shopper-history.json","response":{"results":[{"query_id":"example-shopper","items":[{"merchant_id":"01g4s5d0h956te86ff90h6xts4","merchant_name":"Brooklinen","type":"purchased"},{"merchant_id":"01g4s5dc138qsnh4egsjys8g9c","merchant_name":"Everlane","type":"purchased"},{"merchant_id":"01g4s4gvb1kdc8kz69cm5q2b4f","merchant_name":"NIKE","type":"visited"}]}]},"responseLabel":"Synthetic fixture response"},{"title":"Understand the live request contract","description":"The example hash is not a seeded live shopper. An unknown shopper returns an empty items array, as illustrated here. For an authorized real lookup, substitute the correctly normalized email hash; do not send the raw address.","method":"POST","path":"/v1/shoppers/history","request":{"queries":[{"query_id":"example-shopper","email_sha256":"3a32f737ca25fb3d367dd3c8aaa91e9bf73f31445b0377a8de073eb33276dcb8"}]},"response":{"results":[{"query_id":"example-shopper","items":[]}]}}],"url":"https://openstock.sh/recipes/history","demo_url":"https://openstock.sh/demo?recipe=history"},{"id":"miss","title":"Handle absence without guessing","summary":"Tell an unknown merchant apart from a store with no qualifying code.","purpose":"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.","liveDescription":"Open the demo and select Run recipe to search a deliberately nonexistent .invalid domain. The demo presents the miss directly, without inventing a merchant or discount.","checks":[{"field":"search items[0].id: null","meaning":"The merchant did not resolve. Ask for a better name or domain instead of making a codes request with a guessed ID."},{"field":"codes items: []","meaning":"No code was returned; it does not by itself establish that the merchant is unknown."},{"field":"suppressed_code_count","meaning":"A positive count means the probability threshold or result limit removed candidates."},{"field":"activation_url + cashback","meaning":"A known merchant can still have an activation link. Cashback is available only when its own field is non-null."}],"steps":[{"title":"Resolve an unknown domain","description":"A well-formed search can succeed with no matching merchant. Preserve the null result as normal application data.","method":"POST","path":"/v1/merchants/search","request":{"queries":[{"query_id":"unknown","type":"domain","value":"openstock-no-such-store.invalid"}]},"response":{"results":[{"query_id":"unknown","items":[{"id":null,"name":null,"domains":[],"popularity_rank":null,"estimated_shipping":null}]}]}},{"title":"Filter public codes by your quality bar","description":"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.","method":"POST","path":"/v1/merchants/codes","request":{"queries":[{"query_id":"nike","merchant_id":"01g4s4gvb1kdc8kz69cm5q2b4f","idempotency_key":"replace-with-your-filter-session-key","min_probability":0.5,"limit":3}]},"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":[]}]}}],"url":"https://openstock.sh/recipes/miss","demo_url":"https://openstock.sh/demo?recipe=miss"},{"id":"replay","title":"Replay without issuing another code","summary":"Run one request, then reuse its idempotency key and compare the code.","purpose":"A tool call may be retried after a timeout or by an assistant continuing a session. Keep a stable idempotency key for that offer request so a successful retry reuses the generated code. Compare the returned code; do not assume every response field is a frozen snapshot.","liveDescription":"Select Run recipe for Brooklinen once, then Run again in the demo. It reuses the daily idempotency key within the same UTC day; compare the request keys and generated codes in both runs. After midnight UTC, the demo uses a new key.","checks":[{"field":"idempotency_key","meaning":"Use the same opaque key for the same shopper and offer session. Replace the documentation placeholder; do not share it across real shoppers."},{"field":"code","meaning":"The replay should return the same generated code while the underlying offer is available. A new key represents a new issuance request. The public demo changes its key at midnight UTC."},{"field":"single_use","meaning":"Replaying a single-use code does not reset its redemption state or make it reusable at checkout."},{"field":"conditions + expires_at","meaning":"Continue to respect the returned terms and expiry. A null expiry does not prove the code lasts forever."}],"steps":[{"title":"Request an offer with the merchant ID","description":"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.","method":"POST","path":"/v1/merchants/codes","request":{"queries":[{"query_id":"brooklinen","merchant_id":"01g4s5d0h956te86ff90h6xts4","idempotency_key":"replace-with-your-shopper-session-key","limit":1}]},"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}]}]}},{"title":"Repeat the exact request","description":"Send the same body, including merchant_id and idempotency_key. The repeated illustrative response contains the same code. The demo keeps the original request available in the inspector. Its Run again button reuses the same key within a UTC day; compare both request keys before assessing the generated code.","method":"POST","path":"/v1/merchants/codes","request":{"queries":[{"query_id":"brooklinen","merchant_id":"01g4s5d0h956te86ff90h6xts4","idempotency_key":"replace-with-your-shopper-session-key","limit":1}]},"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}]}]}}],"url":"https://openstock.sh/recipes/replay","demo_url":"https://openstock.sh/demo?recipe=replay"}]}