Heavyweight organic cotton canvas tote with an interior pocket.
", "url": "https://yetch.studio/products/studio-tote-bag", "main_image": "https://cdn.shopify.com/s/files/1/0567/8901/products/studio-tote-natural.jpg", "images": [ "https://cdn.shopify.com/s/files/1/0567/8901/products/studio-tote-natural.jpg", "https://cdn.shopify.com/s/files/1/0567/8901/products/studio-tote-black.jpg" ], "price": 3800, "price_min": 3800, "price_max": 4200, "available": true, "tags": [ "bags", "canvas", "new-arrivals" ], "variants": [ { "variant_id": "42198765432109", "title": "Natural", "sku": "TOTE-NAT", "price": 3800, "available": true }, { "variant_id": "42198765432110", "title": "Black", "sku": "TOTE-BLK", "price": 4200, "available": false } ] } }, "etsy": { "summary": "Etsy", "value": { "status": "completed", "retailer": "etsy", "product_id": "1234567890", "listing_id": "1234567890", "title": "Hand-Thrown Stoneware Mug, 12 oz", "description": "Wheel-thrown stoneware mug with a matte speckled glaze. Dishwasher and microwave safe.", "url": "https://www.etsy.com/listing/1234567890/hand-thrown-stoneware-mug-12-oz", "price": 3400, "currency_code": "USD", "main_image": "https://i.etsystatic.com/12345678/r/il/abcdef/1234567890/il_fullxfull.1234567890_abcd.jpg", "images": [ "https://i.etsystatic.com/12345678/r/il/abcdef/1234567890/il_fullxfull.1234567890_abcd.jpg", "https://i.etsystatic.com/12345678/r/il/abcdef/1234567891/il_fullxfull.1234567891_efgh.jpg" ], "quantity": 8, "available": true, "state": "active", "tags": [ "ceramic mug", "stoneware", "coffee mug" ], "materials": [ "stoneware", "glaze" ], "taxonomy_id": 1103, "who_made": "i_did", "when_made": "made_to_order", "is_supply": false, "is_customizable": true, "listing_type": "physical", "num_favorers": 412, "views": 9871, "has_variations": true, "variants": [ { "variant_id": "9876543210", "sku": "MUG-12-SPECKLE", "price": 3400, "currency_code": "USD", "quantity": 5, "available": true, "properties": [ { "name": "Glaze", "value": "Speckled White" } ] }, { "variant_id": "9876543211", "sku": "MUG-12-SLATE", "price": 3400, "currency_code": "USD", "quantity": 3, "available": true, "properties": [ { "name": "Glaze", "value": "Slate Blue" } ] } ], "shop_name": "RiverbendPottery", "shop_url": "https://www.etsy.com/shop/RiverbendPottery", "shop_review_average": 4.9, "shop_review_count": 263, "shop_is_vacation": false } }, "processing": { "summary": "Still fetching (async=true)", "value": { "status": "processing" } }, "failed": { "summary": "Retailer error", "value": { "status": "failed", "code": "product_not_found", "message": "No product found for id B00KFP6NHO on amazon" } } } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "402": { "description": "Insufficient wallet balance for the data-API fee. Fund the wallet (or check `GET /wallet/me`) and retry. Postpaid plan customers are never gated here.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } }, "required": [ "detail" ] }, "example": { "detail": "Insufficient wallet balance for data API call" } } } } }, "x-metered": { "currency": "USD", "amount": "0.01", "unit": "call", "paid_from": "wallet" } } }, "/search": { "get": { "tags": [ "search" ], "summary": "Search", "description": "Search for products across retailers; returns orderable zn_sku_ listings.\n\n**Billing.** This is a metered data call: $0.01 is drawn from your wallet per successful request, before any order is placed. An empty wallet gets `402` instead. Sandbox (`zn_test_`) calls are free and never touch the live wallet.", "operationId": "search_search_get", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "description": "Search term", "title": "Q" }, "description": "Search term" }, { "name": "min_price", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "description": "Cents. Drop results priced below this.", "title": "Min Price" }, "description": "Cents. Drop results priced below this." }, { "name": "max_price", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "description": "Cents. Drop results priced above this. Pass the `max_price` you intend to send to POST /orders and every result returned fits it. Results with no known price are dropped when a clamp is set.", "title": "Max Price" }, "description": "Cents. Drop results priced above this. Pass the `max_price` you intend to send to POST /orders and every result returned fits it. Results with no known price are dropped when a clamp is set." }, { "name": "retailer", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Only return results from these retailers. Repeat the param for several: `?retailer=amazon&retailer=target`. Takes the discovery retailers (amazon, bestbuy, bhphotovideo, chewy, costco, homedepot, kohls, lowes, macys, newegg, staples, target, walmart, wayfair) and up to 3 catalogued Shopify stores by their Zinc retailer slug (e.g. `retailer=yetch`; a store's domain also works). A filter of only stores searches those stores directly. With a live key, a Shopify store not yet catalogued is added on first use by its domain.", "title": "Retailer" }, "description": "Only return results from these retailers. Repeat the param for several: `?retailer=amazon&retailer=target`. Takes the discovery retailers (amazon, bestbuy, bhphotovideo, chewy, costco, homedepot, kohls, lowes, macys, newegg, staples, target, walmart, wayfair) and up to 3 catalogued Shopify stores by their Zinc retailer slug (e.g. `retailer=yetch`; a store's domain also works). A filter of only stores searches those stores directly. With a live key, a Shopify store not yet catalogued is added on first use by its domain." }, { "name": "sort", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/SearchSort", "description": "Result order. `relevance` (default) blends query match, source rank and rating, and mixes retailers. The explicit sorts order the 20 most relevant results (or `limit`, if larger) that match at least half the query, so accessories that merely name the product don't lead; results with no price (or no rating, for `rating`) sort last.", "default": "relevance" }, "description": "Result order. `relevance` (default) blends query match, source rank and rating, and mixes retailers. The explicit sorts order the 20 most relevant results (or `limit`, if larger) that match at least half the query, so accessories that merely name the product don't lead; results with no price (or no rating, for `rating`) sort last." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 50, "minimum": 1 }, { "type": "null" } ], "description": "Return at most this many results (1-50). One search is one billed call either way.", "title": "Limit" }, "description": "Return at most this many results (1-50). One search is one billed call either way." }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "402": { "description": "Insufficient wallet balance for the data-API fee. Fund the wallet (or check `GET /wallet/me`) and retry. Postpaid plan customers are never gated here.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } }, "required": [ "detail" ] }, "example": { "detail": "Insufficient wallet balance for data API call" } } } } }, "x-metered": { "currency": "USD", "amount": "0.01", "unit": "call", "paid_from": "wallet" } } }, "/managed-accounts": { "get": { "tags": [ "managed-accounts" ], "summary": "List Retailer Credentials", "description": "List all retailer credentials for the current user.\nIf is_global=True (admin only), list global credentials instead.", "operationId": "list_retailer_credentials_managed_accounts_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "description": "Page size (default 50, max 500). Responses include `total` for paging past it.", "default": 50, "title": "Limit" }, "description": "Page size (default 50, max 500). Responses include `total` for paging past it." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Number of credentials to skip", "default": 0, "title": "Offset" }, "description": "Number of credentials to skip" }, { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Partial match on email or retailer", "title": "Search" }, "description": "Partial match on email or retailer" }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetailerCredentialsListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "managed-accounts" ], "summary": "Create Retailer Credentials", "description": "Create new retailer credentials for the current user.\n\nSaving an account does not, on its own, change how orders are placed: an\norder runs on this account only when it passes the returned `short_id` as\n`retailer_credentials_id`. Orders that do are paid for by the payment\nmethod saved on the account and charged the API fee only; every other\norder runs on a Zinc account and draws the item cost from the wallet.\n\nIf is_global=True (admin only), creates global credentials owned by the system user.", "operationId": "create_retailer_credentials_managed_accounts_post", "parameters": [ { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetailerCredentialsCreate" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetailerCredentialsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/managed-accounts/{short_id}": { "put": { "tags": [ "managed-accounts" ], "summary": "Update Retailer Credentials", "description": "Update retailer credentials for the current user.\nAdmins can also update global credentials.", "operationId": "update_retailer_credentials_managed_accounts__short_id__put", "parameters": [ { "name": "short_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Short Id" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetailerCredentialsUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetailerCredentialsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "managed-accounts" ], "summary": "Delete Retailer Credentials", "description": "Delete retailer credentials for the current user.\nAdmins can also delete global credentials.", "operationId": "delete_retailer_credentials_managed_accounts__short_id__delete", "parameters": [ { "name": "short_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Short Id" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/agent/orders": { "post": { "tags": [ "agent" ], "summary": "Buy a product from a major online retailer and ship it to a US address", "description": "Place an order via the Machine Payments Protocol (MPP).\n\nNo Zinc account required. Payment is made upfront via MPP.\nSupports multiple payment methods (e.g. Tempo, Stripe).\nIf no valid payment credential is provided, returns HTTP 402\nwith payment challenges for all configured methods.\n\nPayment is the gate, but only for a genuine discovery probe: a bodyless\nPOST (from a registry like mppscan) is parsed leniently and reaches the 402\nchallenge instead of a 422. A *present-but-invalid* body, by contrast \u2014\nincluding malformed JSON and non-object JSON \u2014 is a real order attempt\nand is rejected with a 422 up front, before any payment\nchallenge is issued or honored. Otherwise an agent could settle an on-chain\npayment against the challenge and then be rejected on the retry, with no way\nto refund the settlement (the MPP layer cannot verify or reverse a payment\nwhose retry body no longer matches the challenge).", "operationId": "create_mpp_order_agent_orders_post", "parameters": [ { "name": "method", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Restrict the 402 to a single payment method (e.g. 'stripe', 'tempo', or 'x402'). Omit to advertise every configured method. Use this when your client can satisfy only one rail \u2014 it avoids returning multiple WWW-Authenticate challenges, which many HTTP clients mishandle.", "title": "Method" }, "description": "Restrict the 402 to a single payment method (e.g. 'stripe', 'tempo', or 'x402'). Omit to advertise every configured method. Use this when your client can satisfy only one rail \u2014 it avoids returning multiple WWW-Authenticate challenges, which many HTTP clients mishandle." }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } } ], "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderResponse" } } }, "headers": { "X-Api-Key": { "description": "API key for the paying agent. Reads the order via GET /orders/{id}, cancels it while pending, and registers a webhook URL via PUT /webhooks/endpoint.", "schema": { "type": "string" } }, "Payment-Receipt": { "description": "MPP payment receipt confirming the charge", "schema": { "type": "string" } } } }, "402": { "description": "Payment required \u2014 returns challenge details for each configured payment method", "headers": { "WWW-Authenticate": { "description": "One header per supported payment method with challenge parameters (per RFC 9110 \u00a711.6.1)", "schema": { "type": "string" } } } }, "409": { "description": "Duplicate `idempotency_key` \u2014 this payer already placed an order under that key. Checked after the payment proof is verified but BEFORE it is settled, so a client that lost the original 201 to a timeout can retry with the same key (and a fresh signed payment) without being charged twice. The existing order's id is in `error.details.order_id`; fetch it with the X-Api-Key header on this response via GET /orders/{id}. Same error shape as POST /orders.", "headers": { "X-Api-Key": { "description": "API key for the payer's account, to look up the existing order", "schema": { "type": "string" } } } }, "422": { "description": "Invalid order body \u2014 rejected before any payment challenge is issued or honored, so a payment can never be taken for an order that would be rejected. Send a valid OrderCreate body, or no body at all to receive a discovery 402." } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderCreate" } } } }, "x-payment-info": { "price": { "mode": "dynamic", "currency": "USD", "min": "1.00", "max": "10000.00" }, "protocols": [ { "mpp": { "method": "", "intent": "charge", "currency": "" } } ] }, "security": [] } }, "/agent/search": { "post": { "tags": [ "agent" ], "summary": "Search products across every supported retailer and get buyable listings", "description": "**Beta** \u2014 response shape may change. Cross-retailer product search for agents. Returns orderable listings whose\n`url` can be passed straight to POST /agent/orders.", "operationId": "agent_search", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "description": "Search term", "title": "Q" }, "description": "Search term" }, { "name": "min_price", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "description": "Cents. Drop results priced below this.", "title": "Min Price" }, "description": "Cents. Drop results priced below this." }, { "name": "max_price", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "description": "Cents. Drop results priced above this. Pass the `max_price` you intend to send to POST /orders and every result returned fits it. Results with no known price are dropped when a clamp is set.", "title": "Max Price" }, "description": "Cents. Drop results priced above this. Pass the `max_price` you intend to send to POST /orders and every result returned fits it. Results with no known price are dropped when a clamp is set." }, { "name": "retailer", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "description": "Only return results from these retailers. Repeat the param for several: `?retailer=amazon&retailer=target`. Takes the discovery retailers (amazon, bestbuy, bhphotovideo, chewy, costco, homedepot, kohls, lowes, macys, newegg, staples, target, walmart, wayfair) and up to 3 catalogued Shopify stores by their Zinc retailer slug (e.g. `retailer=yetch`; a store's domain also works). A filter of only stores searches those stores directly." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "relevance", "price_asc", "price_desc", "rating" ], "default": "relevance" }, "description": "Result order. `relevance` (default) blends query match, source rank and rating, and mixes retailers. The explicit sorts order the 20 most relevant results (or `limit`, if larger) that match at least half the query, so accessories that merely name the product don't lead; results with no price (or no rating, for `rating`) sort last." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50 }, "description": "Return at most this many results (1-50). One search is one billed call either way." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } } }, "402": { "description": "Payment required \u2014 returns an MPP challenge (one WWW-Authenticate header per payable method) and, when configured, an x402 challenge in the PAYMENT-REQUIRED header. Pay with whichever rail you support.", "headers": { "WWW-Authenticate": { "description": "One header per payable MPP method with challenge parameters (per RFC 9110 \u00a711.6.1)", "schema": { "type": "string" } }, "PAYMENT-REQUIRED": { "description": "x402 v2 payment requirements (base64-encoded JSON)", "schema": { "type": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.01" }, "protocols": [ { "mpp": { "method": "", "intent": "charge", "currency": "" } }, { "x402": { "scheme": "exact", "network": "eip155:8453" } } ] }, "security": [], "x-beta": true } }, "/agent/products/search": { "post": { "tags": [ "agent" ], "summary": "Search one retailer's catalog for products", "description": "Per-retailer product search for agents.\n\n**Best Buy returns a partial page.** Best Buy server-renders only about 4 of\nthe ~24 products on a search page and loads the rest in the browser, so each\npage yields roughly 4 results rather than a full page. Ranking, pricing and\navailability are Best Buy's own; there are simply fewer items per page. Page\nthrough with `next_page` to collect more \u2014 `next_page` reflects whether Best\nBuy has further results, not how many came back in this response.\n\n**Shopify stores are their own retailer**: pass the store's Zinc retailer\nslug as `retailer` (e.g. `retailer=yetch`; its domain, `yetch.studio`, also\nworks). The store must be in Zinc's catalog: an uncatalogued store is\nrejected with a 422, and `GET /retailers/check?url=...` returns a\ncatalogued store's slug. Results are the store's own top matches (~10) and there is no\npagination, so `next_page` is always null and `page` must be omitted or 1.\n`product_id` is the store-scoped product handle to pass to the details\nendpoint with the same `retailer`.\n\n**Etsy search covers US shops, priced in USD.** Etsy sellers price in their\nown currency and a single page routinely mixes several, which makes `price`\nincomparable across a result set \u2014 so search is narrowed to US-located\nshops and any remaining non-USD listing is dropped. `currency_code` is set\non every result and is always `USD` here, and prices are never converted,\nso the number is what the seller charges. Because the currency check runs\nafter Etsy paginates, **a page can come back short while more results still\nexist** \u2014 page on with `next_page`. (Details is neither narrowed nor\nfiltered: it returns any listing, in its own currency.)\n\nEtsy results carry no `stars`/`num_reviews` \u2014 Etsy publishes a rating for\nthe *shop*, not the listing, and reporting a seller's rating as the\nproduct's would be misleading; `brand` carries the shop name, and the\ndetails endpoint reports the shop's rating explicitly. `product_id` is the\nnumeric listing id.", "operationId": "agent_product_search", "parameters": [ { "name": "query", "in": "query", "required": true, "schema": { "type": "string", "description": "Search term", "title": "Query" }, "description": "Search term" }, { "name": "retailer", "in": "query", "required": true, "schema": { "type": "string", "description": "Zinc retailer slug: amazon, amazon-uk, amazon-ca, amazon-de, amazon-mx, amazon-fr, walmart, bestbuy, etsy, or a catalogued Shopify store's slug (e.g. retailer=yetch; GET /retailers/check?url=... returns a store's slug). A store's domain is also accepted, as are the older amazon_uk-style codes. Stores not in Zinc's catalog are rejected with a 422. Responses carry the slug.", "title": "Retailer" }, "description": "Zinc retailer slug: amazon, amazon-uk, amazon-ca, amazon-de, amazon-mx, amazon-fr, walmart, bestbuy, etsy, or a catalogued Shopify store's slug (e.g. retailer=yetch; GET /retailers/check?url=... returns a store's slug). A store's domain is also accepted, as are the older amazon_uk-style codes. Stores not in Zinc's catalog are rejected with a 422. Responses carry the slug." }, { "name": "page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Page number for pagination", "title": "Page" }, "description": "Page number for pagination" }, { "name": "free_shipping", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Only return items that ship for free (Walmart and Best Buy: ship price of 0). Currently a no-op for Amazon: the upstream search data under-reports Prime, so filtering on it would drop valid items \u2014 Amazon results are returned unfiltered. Filtering happens after pagination, so per-page counts vary; use `next_page` in the response to keep paging \u2014 an empty page with a non-null `next_page` is not the end of results. Rejected for Shopify stores: their search data carries no shipping information, so the filter cannot be honored.", "default": false, "title": "Free Shipping" }, "description": "Only return items that ship for free (Walmart and Best Buy: ship price of 0). Currently a no-op for Amazon: the upstream search data under-reports Prime, so filtering on it would drop valid items \u2014 Amazon results are returned unfiltered. Filtering happens after pagination, so per-page counts vary; use `next_page` in the response to keep paging \u2014 an empty page with a non-null `next_page` is not the end of results. Rejected for Shopify stores: their search data carries no shipping information, so the filter cannot be honored." } ], "responses": { "200": { "description": "Normalized search results. Common fields are always present; retailer-specific fields are null or omitted for other retailers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductSearchResponse" }, "example": { "status": "completed", "results": [ { "product_id": "B000NPYY04", "title": "Nature's Bounty Fish Oil, 1200 mg Omega-3, 200 Rapid Release Softgels", "image": "https://m.media-amazon.com/images/I/51KGjV22PWL._AC_US218_.jpg", "brand": "Nature's Bounty", "price": 1248, "stars": 4.5, "num_reviews": 39510, "num_offers_estimate": 12, "num_sales": 30000, "product_details": [ "200 Count (Pack of 1)" ], "fresh": false, "prime": true, "pantry": false, "addon": false }, { "product_id": "B004U3Y9FU", "title": "Nature Made Burpless Fish Oil 1000 mg Softgels, 150 Count", "image": "https://m.media-amazon.com/images/I/516F1UWawAL._AC_US218_.jpg", "brand": "Nature Made", "price": 1299, "stars": 4.7, "num_reviews": 22087, "num_offers_estimate": 8, "num_sales": 20000, "product_details": [ "150 Count (Pack of 1)" ], "fresh": false, "prime": true, "pantry": false, "addon": false } ], "next_page": 2 } } } }, "402": { "description": "Payment required \u2014 returns an MPP challenge (one WWW-Authenticate header per payable method) and, when configured, an x402 challenge in the PAYMENT-REQUIRED header. Pay with whichever rail you support.", "headers": { "WWW-Authenticate": { "description": "One header per payable MPP method with challenge parameters (per RFC 9110 \u00a711.6.1)", "schema": { "type": "string" } }, "PAYMENT-REQUIRED": { "description": "x402 v2 payment requirements (base64-encoded JSON)", "schema": { "type": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.01" }, "protocols": [ { "mpp": { "method": "", "intent": "charge", "currency": "" } }, { "x402": { "scheme": "exact", "network": "eip155:8453" } } ] }, "security": [] } }, "/agent/products/offers": { "post": { "tags": [ "agent" ], "summary": "List sellers, prices and availability for one product", "description": "Offers/pricing for a specific product on a retailer.\n\nNot available for Shopify stores: a storefront lists one seller (itself),\nso per-variant price and availability live on the details endpoint instead.", "operationId": "agent_product_offers", "parameters": [ { "name": "product_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Product identifier (e.g. ASIN)", "title": "Product Id" }, "description": "Product identifier (e.g. ASIN)" }, { "name": "retailer", "in": "query", "required": true, "schema": { "type": "string", "description": "Zinc retailer slug: amazon, amazon-uk, amazon-ca, amazon-de, amazon-mx, amazon-fr, walmart, bestbuy, etsy, or a catalogued Shopify store's slug (e.g. retailer=yetch; GET /retailers/check?url=... returns a store's slug). A store's domain is also accepted, as are the older amazon_uk-style codes. Stores not in Zinc's catalog are rejected with a 422. Responses carry the slug.", "title": "Retailer" }, "description": "Zinc retailer slug: amazon, amazon-uk, amazon-ca, amazon-de, amazon-mx, amazon-fr, walmart, bestbuy, etsy, or a catalogued Shopify store's slug (e.g. retailer=yetch; GET /retailers/check?url=... returns a store's slug). A store's domain is also accepted, as are the older amazon_uk-style codes. Stores not in Zinc's catalog are rejected with a 422. Responses carry the slug." }, { "name": "max_age", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 31 }, { "type": "null" } ], "description": "Max response age in seconds, at least 31 (mutually exclusive with newer_than)", "title": "Max Age" }, "description": "Max response age in seconds, at least 31 (mutually exclusive with newer_than)" }, { "name": "newer_than", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Minimum retrieval timestamp, as a unix time (mutually exclusive with max_age). Windows shorter than 31s are widened to it.", "title": "Newer Than" }, "description": "Minimum retrieval timestamp, as a unix time (mutually exclusive with max_age). Windows shorter than 31s are widened to it." }, { "name": "async", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Return immediately with status=processing", "title": "Async" }, "description": "Return immediately with status=processing" } ], "responses": { "200": { "description": "Seller offers for the product, passed through from the retailer. `status` is always present; `offers` is populated when `status` is `completed`.", "content": { "application/json": { "schema": { "title": "ProductOffers", "type": "object", "description": "Every seller's offer for the product, passed through from the retailer. Shopify stores and Etsy listings have a single seller, so they are rejected here and report price and availability on the details endpoint; Best Buy's per-condition prices are on the details endpoint too.", "properties": { "status": { "type": "string", "enum": [ "completed", "processing", "failed" ], "description": "`completed` when the payload below is populated. `processing` when `async=true` was passed and the fetch is still running \u2014 poll again. `failed` when the retailer returned an error; see `code` and `message`." }, "code": { "type": "string", "description": "Only on `status: failed`. Machine-readable error code, e.g. `product_not_found`, `invalid_request`." }, "message": { "type": "string", "description": "Only on `status: failed`. Human-readable explanation." }, "retailer": { "type": "string", "description": "Zinc retailer slug that served the offers, e.g. `amazon`." }, "asin": { "type": "string", "description": "Amazon only. The product's ASIN." }, "offers": { "type": "array", "items": { "title": "ProductOffer", "type": "object", "properties": { "offer_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Retailer's identifier for this offer. Amazon: the offer listing id." }, "price": { "type": "integer", "description": "Item price in cents, excluding shipping." }, "condition": { "type": "string", "description": "Item condition.", "enum": [ "New", "Refurbished", "Used - Like New", "Used - Very Good", "Used - Good", "Used - Acceptable", "Unacceptable" ] }, "available": { "type": "boolean", "description": "Whether the offer can currently be bought." }, "seller": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Retailer's seller id." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Seller display name." }, "num_ratings": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Seller's lifetime rating count." }, "percent_positive": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Share of positive seller ratings, 0\u2013100." }, "first_party": { "type": "boolean", "description": "Sold by the retailer itself (e.g. Amazon.com)." } }, "description": "Who is selling this offer." }, "marketplace_fulfilled": { "type": "boolean", "description": "Shipped by the retailer rather than the seller. Amazon: the offer ships with Prime." }, "prime_only": { "type": "boolean", "description": "Amazon only. Only Prime members can buy this offer." }, "international": { "type": "boolean", "description": "Ships from outside the United States." }, "addon": { "type": "boolean", "description": "Amazon only. Add-on item that can only be bought alongside other items." }, "minimum_quantity": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Minimum order quantity, when the seller imposes one." }, "handling_days": { "type": "object", "properties": { "min": { "type": "integer", "description": "Minimum handling time in days." }, "max": { "type": "integer", "description": "Maximum handling time in days." } }, "description": "Time before the seller ships." }, "shipping_options": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Shipping speed, e.g. `standard`, `one-day`." }, "price": { "type": "integer", "description": "Shipping price in cents." }, "delivery_days": { "type": "object", "properties": { "min": { "type": "integer", "description": "Earliest delivery, in days." }, "max": { "type": "integer", "description": "Latest delivery, in days." } } } } }, "description": "Shipping methods offered by this seller." } } }, "description": "One entry per seller offer. Empty when the product has no buyable offers." }, "timestamp": { "type": "integer", "description": "Unix time the offers were retrieved." } }, "required": [ "status" ], "additionalProperties": true }, "examples": { "amazon": { "summary": "Amazon", "value": { "status": "completed", "retailer": "amazon", "asin": "B00KFP6NHO", "offers": [ { "offer_id": "5ZwHjTcqVwZHZmB3IOKCbwUmf5NmT1fnfGhbwOQ0B5", "price": 799, "condition": "New", "available": true, "seller": { "id": "ATVPDKIKX0DER", "name": "Amazon.com", "first_party": true }, "marketplace_fulfilled": true, "prime_only": false, "international": false, "addon": false, "handling_days": { "min": 0, "max": 0 }, "shipping_options": [ { "name": "standard", "price": 0, "delivery_days": { "min": 2, "max": 5 } }, { "name": "one-day", "price": 599, "delivery_days": { "min": 1, "max": 1 } } ] }, { "offer_id": "eMLzuculxk", "price": 628, "condition": "Used - Very Good", "available": true, "seller": { "id": "A2L77EE7U53NWQ", "name": "Amazon Warehouse", "num_ratings": 218432, "percent_positive": 93, "first_party": false }, "marketplace_fulfilled": true, "prime_only": false, "international": false, "addon": false, "handling_days": { "min": 0, "max": 1 }, "shipping_options": [ { "name": "standard", "price": 0, "delivery_days": { "min": 4, "max": 4 } } ] } ], "timestamp": 1756425600 } }, "processing": { "summary": "Still fetching (async=true)", "value": { "status": "processing" } }, "failed": { "summary": "Retailer error", "value": { "status": "failed", "code": "product_not_found", "message": "No product found for id B00KFP6NHO on amazon" } } } } } }, "402": { "description": "Payment required \u2014 returns an MPP challenge (one WWW-Authenticate header per payable method) and, when configured, an x402 challenge in the PAYMENT-REQUIRED header. Pay with whichever rail you support.", "headers": { "WWW-Authenticate": { "description": "One header per payable MPP method with challenge parameters (per RFC 9110 \u00a711.6.1)", "schema": { "type": "string" } }, "PAYMENT-REQUIRED": { "description": "x402 v2 payment requirements (base64-encoded JSON)", "schema": { "type": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.01" }, "protocols": [ { "mpp": { "method": "", "intent": "charge", "currency": "" } }, { "x402": { "scheme": "exact", "network": "eip155:8453" } } ] }, "security": [] } }, "/agent/products/details": { "post": { "tags": [ "agent" ], "summary": "Get full details for one product", "description": "Full product details for a specific product on a retailer.\n\n**Best Buy is addressed by `bsin`**, not by the numeric SKU \u2014 the bsin is the\ntrailing id in a Best Buy product URL (`/product/{slug}/{bsin}`). Search\nresults return the SKU as `product_id` and also carry the bsin, so pass the\nbsin here. The response repeats the SKU as `sku` for cross-referencing.\n\nUnlike `/search`, a Best Buy detail response is complete: detail pages are\nfully server-rendered, so nothing is withheld for client-side loading.\n\n**Shopify is addressed by (store, handle)**: pass the store's retailer slug\nas `retailer` (e.g. `retailer=yetch`) and the product handle \u2014 the slug\nin `/products/{handle}`, returned as `product_id` by search \u2014 as\n`product_id`. The response includes per-variant price and availability,\n`retailer` (the store's slug) and `platform: \"shopify\"`. `async` is not\nsupported for Shopify stores.\n\n**Etsy is addressed by the numeric listing id** (returned as `product_id` by\nsearch). `price` is in minor units of `currency_code`, not converted to USD.\n\nEtsy ratings are the **shop's**, reported as `shop_review_average` /\n`shop_review_count`, and both cover only the **past year** \u2014 an established\nshop with no recent sales reports 0, and an unrated shop reports a null\naverage rather than 0.0 stars. `stars` and `num_reviews` are deliberately\nnot set: they mean a product's rating everywhere else in this API, and a\nseller's rating is a different claim.\n\n`listing_type` is `physical`, `download` or `both` \u2014 a download has nothing\nto ship. `available` accounts for the shop being on vacation as well as\nstock, so it can be false on an in-stock active listing; `shop_is_vacation`\nsays which it was. `variants` is populated only when Etsy exposes a\nlisting's inventory matrix \u2014 check `has_variations` to tell \"no variants\"\nfrom \"variants not visible\". `taxonomy_id` is Etsy's raw category id; there\nis no category name yet. `async` is not supported for Etsy.", "operationId": "agent_product_details", "parameters": [ { "name": "product_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Product identifier (e.g. ASIN)", "title": "Product Id" }, "description": "Product identifier (e.g. ASIN)" }, { "name": "retailer", "in": "query", "required": true, "schema": { "type": "string", "description": "Zinc retailer slug: amazon, amazon-uk, amazon-ca, amazon-de, amazon-mx, amazon-fr, walmart, bestbuy, etsy, or a catalogued Shopify store's slug (e.g. retailer=yetch; GET /retailers/check?url=... returns a store's slug). A store's domain is also accepted, as are the older amazon_uk-style codes. Stores not in Zinc's catalog are rejected with a 422. Responses carry the slug.", "title": "Retailer" }, "description": "Zinc retailer slug: amazon, amazon-uk, amazon-ca, amazon-de, amazon-mx, amazon-fr, walmart, bestbuy, etsy, or a catalogued Shopify store's slug (e.g. retailer=yetch; GET /retailers/check?url=... returns a store's slug). A store's domain is also accepted, as are the older amazon_uk-style codes. Stores not in Zinc's catalog are rejected with a 422. Responses carry the slug." }, { "name": "max_age", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 31 }, { "type": "null" } ], "description": "Max response age in seconds, at least 31 (mutually exclusive with newer_than)", "title": "Max Age" }, "description": "Max response age in seconds, at least 31 (mutually exclusive with newer_than)" }, { "name": "newer_than", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Minimum retrieval timestamp, as a unix time (mutually exclusive with max_age). Windows shorter than 31s are widened to it.", "title": "Newer Than" }, "description": "Minimum retrieval timestamp, as a unix time (mutually exclusive with max_age). Windows shorter than 31s are widened to it." }, { "name": "async", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Return immediately with status=processing", "title": "Async" }, "description": "Return immediately with status=processing" } ], "responses": { "200": { "description": "Product details. The payload is the retailer's, passed through unmodified, so the exact field set depends on `retailer` \u2014 the schema below lists every field each retailer returns, and the example dropdown shows one real response per retailer. `status` is always present.", "content": { "application/json": { "schema": { "title": "ProductDetails", "type": "object", "description": "Product details, passed through from the retailer. Common fields are listed first; fields marked with a retailer name are only present in that retailer's payload. Anything the retailer returns that is not listed here is passed through as well.", "properties": { "status": { "type": "string", "enum": [ "completed", "processing", "failed" ], "description": "`completed` when the payload below is populated. `processing` when `async=true` was passed and the fetch is still running \u2014 poll again. `failed` when the retailer returned an error; see `code` and `message`." }, "code": { "type": "string", "description": "Only on `status: failed`. Machine-readable error code, e.g. `product_not_found`, `invalid_request`." }, "message": { "type": "string", "description": "Only on `status: failed`. Human-readable explanation." }, "retailer": { "type": "string", "description": "Zinc retailer slug that served the payload, the value to pass back as `retailer`: `amazon`, `amazon-uk`, `walmart`, `bestbuy`, `etsy`, or a Shopify store's slug (e.g. `yetch`, with `platform: \"shopify\"` and the store's hostname in `domain`)." }, "platform": { "type": "string", "description": "Shopify only. The commerce platform the store runs on: `shopify`." }, "product_id": { "type": "string", "description": "Identifier you passed in: ASIN (Amazon), item id (Walmart), bsin (Best Buy), product handle (Shopify), or listing id (Etsy)." }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Product title." }, "brand": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Brand or manufacturer. Shopify: the store's `vendor`. Etsy: not set \u2014 see `shop_name`." }, "main_image": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "URL of the primary product image." }, "images": { "type": "array", "items": { "type": "string" }, "description": "URLs of all product images." }, "product_description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Long-form description (Amazon, Walmart, Best Buy). Shopify and Etsy use `description`." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Long-form description (Shopify, Etsy). Plain text on Etsy; may contain HTML on Shopify." }, "price": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Price in cents (minor units of `currency_code` on Etsy). Amazon: the buy-box price, which is not always present and is often not the cheapest offer \u2014 use the offers endpoint for pricing. Best Buy: the `New` condition price. Shopify: the default variant's price." }, "stars": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Average product rating, 0\u20135 (Amazon, Walmart, Best Buy). Not set on Etsy \u2014 see `shop_review_average`." }, "review_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Number of product reviews (Amazon, Walmart)." }, "num_reviews": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Number of product reviews (Best Buy)." }, "feature_bullets": { "type": "array", "items": { "type": "string" }, "description": "Highlight bullets (Amazon, Walmart, Best Buy)." }, "product_details": { "type": "array", "items": { "type": "string" }, "description": "Specification lines, e.g. `Item model number: 5438` (Amazon, Walmart, Best Buy)." }, "categories": { "type": "array", "items": { "type": "string" }, "description": "Category breadcrumb, broadest first (Amazon, Walmart, Best Buy)." }, "variant_specifics": { "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string", "description": "Variant axis, e.g. `Color` or `Size`." }, "value": { "type": "string", "description": "Value on that axis, e.g. `Black` or `Large`." } } }, "description": "The variant axes and values that identify *this* product (Amazon, Walmart, Best Buy)." }, "all_variants": { "type": "array", "items": { "type": "object", "properties": { "product_id": { "type": "string", "description": "Identifier of that variant." }, "variant_specifics": { "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string", "description": "Variant axis, e.g. `Color` or `Size`." }, "value": { "type": "string", "description": "Value on that axis, e.g. `Black` or `Large`." } } }, "description": "Axis/value pairs for that variant." } } }, "description": "Every sibling variant of this product and its identifier (Amazon, Walmart)." }, "epids": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Identifier type: `UPC`, `EAN`, `MPN`, \u2026" }, "value": { "type": "string", "description": "Identifier value." } } }, "description": "External product identifiers (Amazon, Walmart, Best Buy)." }, "epids_map": { "type": "object", "properties": {}, "additionalProperties": { "type": "string" }, "description": "The same identifiers keyed by type, e.g. `{\"UPC\": \"048526054381\"}` (Amazon, Walmart)." }, "timestamp": { "type": "integer", "description": "Unix time the retailer page was retrieved (Amazon, Walmart)." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Canonical product URL (Shopify, Etsy)." }, "available": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether the product can currently be bought (Shopify, Etsy). Etsy: false while the shop is on vacation even if stock exists \u2014 see `shop_is_vacation`." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Merchant-assigned tags (Shopify, Etsy)." }, "asin": { "type": "string", "description": "Amazon only. The product's ASIN." }, "original_retail_price": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Amazon only. Crossed-out list price in cents, when the retailer shows one." }, "ship_price": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Amazon only. Shipping price in cents." }, "question_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Amazon only. Number of customer questions." }, "package_dimensions": { "type": "object", "properties": { "weight": { "type": "object", "properties": { "amount": { "type": "number", "description": "Numeric amount." }, "unit": { "type": "string", "description": "Unit, e.g. `inches`, `ounces`, `pounds`." } } }, "size": { "type": "object", "properties": { "width": { "type": "object", "properties": { "amount": { "type": "number", "description": "Numeric amount." }, "unit": { "type": "string", "description": "Unit, e.g. `inches`, `ounces`, `pounds`." } } }, "depth": { "type": "object", "properties": { "amount": { "type": "number", "description": "Numeric amount." }, "unit": { "type": "string", "description": "Unit, e.g. `inches`, `ounces`, `pounds`." } } }, "length": { "type": "object", "properties": { "amount": { "type": "number", "description": "Numeric amount." }, "unit": { "type": "string", "description": "Unit, e.g. `inches`, `ounces`, `pounds`." } } } } } }, "description": "Amazon only. Shipping weight and package size." }, "authors": { "type": "array", "items": { "type": "string" }, "description": "Amazon only. Author names, for books." }, "aplus_html": { "type": "string", "description": "Amazon only. `present` when the listing has A+ marketing content. The HTML itself is not returned." }, "fresh": { "type": "boolean", "description": "Amazon only. Amazon Fresh item." }, "pantry": { "type": "boolean", "description": "Amazon only. Amazon Pantry item." }, "handmade": { "type": "boolean", "description": "Amazon only. Amazon Handmade item." }, "digital": { "type": "boolean", "description": "Amazon only. Digital-only item (software, video, game codes). Zinc cannot order these." }, "buyapi_hint": { "type": "boolean", "description": "Amazon only. `false` when the item cannot be ordered through Zinc; `true` when it might be." }, "sku": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Best Buy only. Numeric SKU, for cross-referencing with search results (which return the SKU as `product_id`)." }, "product_url": { "type": "string", "description": "Best Buy only. Canonical product URL." }, "offers": { "type": "array", "items": { "type": "object", "properties": { "condition": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Best Buy's own label: `New`, `Open-Box Excellent`, \u2026" }, "price": { "type": "integer", "description": "Price in cents for this condition." }, "availability": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`InStock`, `OutOfStock`, `PreOrder`, \u2026" }, "new": { "type": "boolean", "description": "Whether this is the new-condition offer." }, "seller": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Seller name." } } }, "description": "Best Buy only. Price per condition (new plus each open-box grade). For Amazon and Walmart offers use the offers endpoint." }, "domain": { "type": "string", "description": "Shopify only. Store hostname you passed as `retailer`." }, "handle": { "type": "string", "description": "Shopify only. Product handle (same value as `product_id`)." }, "shopify_product_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Shopify only. The store's numeric product id." }, "product_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Shopify only. The store's product type." }, "price_min": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Shopify only. Cheapest variant price in cents." }, "price_max": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Shopify only. Most expensive variant price in cents." }, "listing_id": { "type": "string", "description": "Etsy only. Listing id (same as `product_id`)." }, "currency_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Etsy only. ISO 4217 currency of `price`, e.g. `USD`, `EUR`. Prices are not converted." }, "quantity": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Etsy only. Units the shop has in stock." }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Etsy only. Listing state: `active`, `inactive`, `sold_out`, `expired`, \u2026" }, "materials": { "type": "array", "items": { "type": "string" }, "description": "Etsy only. Materials listed by the shop." }, "taxonomy_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Etsy only. Etsy's category id. No category name is returned." }, "who_made": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Etsy only. `i_did`, `someone_else`, or `collective`." }, "when_made": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Etsy only. Etsy's production-era bucket, e.g. `made_to_order`, `2020_2026`, `before_2006`." }, "is_supply": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Etsy only. Craft supply, not a finished good." }, "is_customizable": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Etsy only. Buyer can request customization." }, "listing_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Etsy only. `physical`, `download`, or `both`. A download has nothing to ship." }, "num_favorers": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Etsy only. Users who favorited the listing." }, "views": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Etsy only. Listing view count." }, "has_variations": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Etsy only. Whether the listing has variants at all. When true but `variants` is empty, Etsy did not expose the inventory matrix." }, "shop_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Etsy only. Selling shop's name." }, "shop_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Etsy only. Selling shop's URL." }, "shop_review_average": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Etsy only. The **shop's** average rating over the past year, 0\u20135. Null when the shop has no recent reviews." }, "shop_review_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Etsy only. The shop's review count over the past year." }, "shop_is_vacation": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Etsy only. Shop is on vacation mode." }, "variants": { "type": "array", "items": { "type": "object", "properties": { "variant_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Variant id. Shopify: pass it when ordering to pick this variant." }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Shopify only. Variant title, e.g. `Black / Large`." }, "sku": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Merchant SKU." }, "price": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Price in cents (minor units of `currency_code` on Etsy)." }, "currency_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Etsy only. Currency of `price`." }, "quantity": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Etsy only. Units in stock." }, "available": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether this variant can be bought." }, "properties": { "type": "array", "items": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Axis, e.g. `Color`." }, "value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Value, e.g. `Blue`." } } }, "description": "Etsy only. Axis/value pairs that identify this variant." } } }, "description": "Shopify and Etsy only. Per-variant price and availability. Amazon and Walmart use `variant_specifics` / `all_variants` instead." } }, "required": [ "status" ], "additionalProperties": true }, "examples": { "amazon": { "summary": "Amazon", "value": { "status": "completed", "retailer": "amazon", "product_id": "B00KFP6NHO", "asin": "B00KFP6NHO", "title": "Nuby Garden Fresh Fruitsicle Frozen Pop Tray", "brand": "Nuby", "price": 799, "original_retail_price": 899, "ship_price": 0, "stars": 4.4, "review_count": 829, "question_count": 44, "main_image": "https://m.media-amazon.com/images/I/61K0YbuLi-L.jpg", "images": [ "https://m.media-amazon.com/images/I/61K0YbuLi-L.jpg", "https://m.media-amazon.com/images/I/81KtOn8ddTL.jpg", "https://m.media-amazon.com/images/I/71%2BruDKMSoL.jpg" ], "feature_bullets": [ "Includes four freeze-and-feed popsicle molds with handles shaped for little hands", "Wide popsicle-holder base catches drips as the popsicle melts", "6 Months + / BPA Free" ], "product_description": "Nuby's Garden Fresh Fruitsicle Frozen Popsicle Tray is specially designed for making fresh puree popsicles at home. This set includes four fruitsicle handles and a tray to mold the pops.", "product_details": [ "Product Dimensions: 5.8 x 5.8 x 4 inches ; 7.8 ounces", "Shipping Weight: 8.5 ounces", "UPC: 048526054381", "Item model number: 5438" ], "categories": [ "Home & Kitchen", "Kitchen & Dining", "Kitchen Utensils & Gadgets", "Ice Pop Molds" ], "variant_specifics": [ { "dimension": "Size", "value": "1" } ], "all_variants": [ { "product_id": "B00KFP6NHO", "variant_specifics": [ { "dimension": "Size", "value": "1" } ] }, { "product_id": "B00Q3H18EQ", "variant_specifics": [ { "dimension": "Size", "value": "2" } ] } ], "epids": [ { "type": "MPN", "value": "5438" }, { "type": "UPC", "value": "048526054381" }, { "type": "EAN", "value": "0048526054381" } ], "epids_map": { "MPN": "5438", "UPC": "048526054381", "EAN": "0048526054381" }, "package_dimensions": { "weight": { "amount": 8.5, "unit": "ounces" }, "size": { "width": { "amount": 4, "unit": "inches" }, "depth": { "amount": 5.8, "unit": "inches" }, "length": { "amount": 5.8, "unit": "inches" } } }, "aplus_html": "present", "fresh": false, "pantry": false, "handmade": false, "digital": false, "buyapi_hint": true, "timestamp": 1756425600 } }, "bestbuy": { "summary": "Best Buy", "value": { "status": "completed", "retailer": "bestbuy", "product_id": "JJGWKYZY27", "sku": "6668002", "title": "Sony - WH-1000XM5 Wireless Noise-Canceling Over-the-Ear Headphones - Black", "brand": "Sony", "price": 39999, "stars": 4.6, "num_reviews": 3128, "main_image": "https://pisces.bbystatic.com/image2/BestBuy_US/images/products/6668/6668002_sd.jpg", "images": [ "https://pisces.bbystatic.com/image2/BestBuy_US/images/products/6668/6668002_sd.jpg", "https://pisces.bbystatic.com/image2/BestBuy_US/images/products/6668/6668002cv11d.jpg" ], "product_description": "Industry-leading noise canceling with two processors and eight microphones, plus up to 30 hours of battery life.", "feature_bullets": [ "Industry-leading noise canceling: Two processors control eight microphones for unprecedented noise cancellation.", "Up to 30-hour battery life: Quick charging gives you 3 hours of playback from a 3-minute charge." ], "product_details": [ "Wireless Connectivity: Bluetooth", "Battery Life: 30 hours", "Color: Black" ], "categories": [ "Audio", "Headphones", "All Headphones" ], "variant_specifics": [ { "dimension": "Color", "value": "Black" } ], "epids": [ { "type": "UPC", "value": "027242923553" }, { "type": "MPN", "value": "WH1000XM5/B" } ], "offers": [ { "condition": "New", "price": 39999, "availability": "InStock", "new": true, "seller": "Best Buy" }, { "condition": "Open-Box Excellent", "price": 33599, "availability": "InStock", "new": false, "seller": "Best Buy" } ], "product_url": "https://www.bestbuy.com/product/sony-wh-1000xm5-wireless-noise-canceling-over-the-ear-headphones-black/JJGWKYZY27" } }, "shopify": { "summary": "Shopify store", "value": { "status": "completed", "retailer": "yetch", "platform": "shopify", "domain": "yetch.studio", "product_id": "studio-tote-bag", "handle": "studio-tote-bag", "shopify_product_id": "7431029563462", "title": "Studio Tote Bag", "brand": "Yetch Studio", "product_type": "Bags", "description": "Heavyweight organic cotton canvas tote with an interior pocket.
", "url": "https://yetch.studio/products/studio-tote-bag", "main_image": "https://cdn.shopify.com/s/files/1/0567/8901/products/studio-tote-natural.jpg", "images": [ "https://cdn.shopify.com/s/files/1/0567/8901/products/studio-tote-natural.jpg", "https://cdn.shopify.com/s/files/1/0567/8901/products/studio-tote-black.jpg" ], "price": 3800, "price_min": 3800, "price_max": 4200, "available": true, "tags": [ "bags", "canvas", "new-arrivals" ], "variants": [ { "variant_id": "42198765432109", "title": "Natural", "sku": "TOTE-NAT", "price": 3800, "available": true }, { "variant_id": "42198765432110", "title": "Black", "sku": "TOTE-BLK", "price": 4200, "available": false } ] } }, "etsy": { "summary": "Etsy", "value": { "status": "completed", "retailer": "etsy", "product_id": "1234567890", "listing_id": "1234567890", "title": "Hand-Thrown Stoneware Mug, 12 oz", "description": "Wheel-thrown stoneware mug with a matte speckled glaze. Dishwasher and microwave safe.", "url": "https://www.etsy.com/listing/1234567890/hand-thrown-stoneware-mug-12-oz", "price": 3400, "currency_code": "USD", "main_image": "https://i.etsystatic.com/12345678/r/il/abcdef/1234567890/il_fullxfull.1234567890_abcd.jpg", "images": [ "https://i.etsystatic.com/12345678/r/il/abcdef/1234567890/il_fullxfull.1234567890_abcd.jpg", "https://i.etsystatic.com/12345678/r/il/abcdef/1234567891/il_fullxfull.1234567891_efgh.jpg" ], "quantity": 8, "available": true, "state": "active", "tags": [ "ceramic mug", "stoneware", "coffee mug" ], "materials": [ "stoneware", "glaze" ], "taxonomy_id": 1103, "who_made": "i_did", "when_made": "made_to_order", "is_supply": false, "is_customizable": true, "listing_type": "physical", "num_favorers": 412, "views": 9871, "has_variations": true, "variants": [ { "variant_id": "9876543210", "sku": "MUG-12-SPECKLE", "price": 3400, "currency_code": "USD", "quantity": 5, "available": true, "properties": [ { "name": "Glaze", "value": "Speckled White" } ] }, { "variant_id": "9876543211", "sku": "MUG-12-SLATE", "price": 3400, "currency_code": "USD", "quantity": 3, "available": true, "properties": [ { "name": "Glaze", "value": "Slate Blue" } ] } ], "shop_name": "RiverbendPottery", "shop_url": "https://www.etsy.com/shop/RiverbendPottery", "shop_review_average": 4.9, "shop_review_count": 263, "shop_is_vacation": false } }, "processing": { "summary": "Still fetching (async=true)", "value": { "status": "processing" } }, "failed": { "summary": "Retailer error", "value": { "status": "failed", "code": "product_not_found", "message": "No product found for id B00KFP6NHO on amazon" } } } } } }, "402": { "description": "Payment required \u2014 returns an MPP challenge (one WWW-Authenticate header per payable method) and, when configured, an x402 challenge in the PAYMENT-REQUIRED header. Pay with whichever rail you support.", "headers": { "WWW-Authenticate": { "description": "One header per payable MPP method with challenge parameters (per RFC 9110 \u00a711.6.1)", "schema": { "type": "string" } }, "PAYMENT-REQUIRED": { "description": "x402 v2 payment requirements (base64-encoded JSON)", "schema": { "type": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.01" }, "protocols": [ { "mpp": { "method": "", "intent": "charge", "currency": "" } }, { "x402": { "scheme": "exact", "network": "eip155:8453" } } ] }, "security": [] } }, "/returns": { "post": { "tags": [ "returns" ], "summary": "Create Return Request", "operationId": "create_return_request_returns_post", "parameters": [ { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnRequestCreate" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnRequestResponse" } } } }, "409": { "description": "An open return request already exists for this order, or a requested item was already part of a prior return request (any status) and is no longer returnable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "returns" ], "summary": "List Return Requests", "operationId": "list_return_requests_returns_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "description": "Page size (default 50, max 500). Responses include `total` for paging past it.", "default": 50, "title": "Limit" }, "description": "Page size (default 50, max 500). Responses include `total` for paging past it." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Number of returns to skip", "default": 0, "title": "Offset" }, "description": "Number of returns to skip" }, { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Partial match on order ID", "title": "Search" }, "description": "Partial match on order ID" }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by return status", "title": "Status" }, "description": "Filter by return status" }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnRequestListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/returns/{return_request_id}": { "get": { "tags": [ "returns" ], "summary": "Get Return Request", "operationId": "get_return_request_returns__return_request_id__get", "parameters": [ { "name": "return_request_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Return Request Id" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnRequestResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/retailers": { "get": { "tags": [ "retailers" ], "summary": "List Retailers", "description": "List the retailers Zinc supports \u2014 the public \"what do you support?\" catalog.\n\nNo authentication required. One flat object per retailer brand: identifier,\ndomain, countries shipped to, and the free-shipping policy. International\nmarketplaces (e.g. amazon.com / amazon.de) are grouped under one brand with\nthe country listed in `supported_countries`. Optionally filter by name.", "operationId": "list_retailers_retailers_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "description": "Number of retailers to return", "default": 100, "title": "Limit" }, "description": "Number of retailers to return" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Number of retailers to skip", "default": 0, "title": "Offset" }, "description": "Number of retailers to skip" }, { "name": "name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by name (case-insensitive partial match)", "title": "Name" }, "description": "Filter by name (case-insensitive partial match)" }, { "name": "include", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass `all` to include the long tail Zinc has ordered from but not curated (hundreds of brands). Omit for the curated set. This selects how much of the catalog to return; it is not a filter on an entry's `support` tier.", "title": "Include" }, "description": "Pass `all` to include the long tail Zinc has ordered from but not curated (hundreds of brands). Omit for the curated set. This selects how much of the catalog to return; it is not a filter on an entry's `support` tier." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicRetailerListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [] } }, "/retailers/check": { "get": { "tags": [ "retailers" ], "summary": "Check Retailer", "description": "Can Zinc buy from this store, and ship it to this country?\n\nNo authentication. This is the question `GET /retailers` cannot answer: the\nlist is the curated set, while the order path accepts most stores, so a\ncaller holding an arbitrary URL has no way to find out from the list alone.\n\n`orderable` is the answer. `support` says how much we know:\n\n| tier | meaning |\n|---|---|\n| `verified` | curated, and its daily test order is passing |\n| `active` | real orders succeeded here in the last 90 days |\n| `observed` | Zinc has attempted orders here |\n| `untested` | never seen \u2014 and Zinc will still attempt it |\n| `unsupported` | Zinc refuses; `unsupported_reason` says why |\n\nRead-only: asking never adds a store to the catalog.", "operationId": "check_retailer_retailers_check_get", "parameters": [ { "name": "url", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 2048, "description": "A product or store URL, e.g. https://shop.aloyoga.com/products/x", "title": "Url" }, "description": "A product or store URL, e.g. https://shop.aloyoga.com/products/x" }, { "name": "country", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ], "description": "Destination country as an ISO 3166-1 alpha-2 code (e.g. 'US', 'GB'). Case-insensitive. Longer spellings such as 'USA' are rejected \u2014 the error names the code to use. Omit to skip the shipping check. Runs the same gate `POST /orders` applies, so the two cannot disagree.", "title": "Country" }, "description": "Destination country as an ISO 3166-1 alpha-2 code (e.g. 'US', 'GB'). Case-insensitive. Longer spellings such as 'USA' are rejected \u2014 the error names the code to use. Omit to skip the shipping check. Runs the same gate `POST /orders` applies, so the two cannot disagree." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetailerCheckResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [] } }, "/usage": { "get": { "tags": [ "usage" ], "summary": "Get My Usage", "description": "The caller's own data-API usage over a trailing window, per endpoint.", "operationId": "get_my_usage_usage_get", "parameters": [ { "name": "window_days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 90, "minimum": 1, "description": "Trailing window in days (max 90).", "default": 30, "title": "Window Days" }, "description": "Trailing window in days (max 90)." }, { "name": "recent", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 0, "description": "How many recent calls to return.", "default": 50, "title": "Recent" }, "description": "How many recent calls to return." }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserUsageResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/wallet/me": { "get": { "tags": [ "wallet" ], "summary": "Get Wallet", "description": "Get your wallet balance.\n\nAll amounts are integer cents. `balance` is the ledger balance;\n`spendable_balance` is what `POST /orders` actually checks against (the two\ndiffer only for Zinc Connect accounts with in-flight holds). An order needs\n`max_price + order_fee_cents` spendable, so compare against that before\nplacing one instead of discovering a shortfall as a 402. Bulk-deal customers\n(`billed_by_invoice: true`) are invoiced monthly and skip the balance check.\n\nUnder a `zn_test_` key (or `X-Test-Mode`) this reads the sandbox wallet,\nwhich sandbox orders never draw down. Funds are added from the dashboard.", "operationId": "get_wallet_wallet_me_get", "parameters": [ { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/stats/delivery-map": { "get": { "tags": [ "stats" ], "summary": "Get Delivery Map", "description": "Recent delivered orders as anonymized, city-level map points.\n\nPublic and unauthenticated \u2014 feeds the marketing site's globe. Points are\nZIP-centroid coordinates rounded to two decimals with a curated category\nemoji; deduplicated and capped. Cached for about an hour.", "operationId": "get_delivery_map_stats_delivery_map_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryMapResponse" } } } } } } }, "/stats/lifetime": { "get": { "tags": [ "stats" ], "summary": "Get Lifetime Stats", "description": "Zinc's all-time successful-order count and GMV.\n\nPublic and unauthenticated. Top-level numbers are v2 (this service);\n``v1`` is the worker-computed legacy snapshot (seed until the first\ncompute lands); ``combined`` sums both. Cached for about a day.", "operationId": "get_lifetime_stats_stats_lifetime_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LifetimeStatsResponse" } } } } } } }, "/track/{order_id}": { "get": { "tags": [ "tracking" ], "summary": "Get Public Tracking", "description": "Public tracking view for a single order, keyed by its UUID.", "operationId": "get_public_tracking_track__order_id__get", "parameters": [ { "name": "order_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Order Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicTrackingResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/sandbox/keys": { "post": { "tags": [ "sandbox" ], "summary": "Mint a sandbox API key (no account needed)", "description": "Mint a provisional sandbox user + test API key. No account needed.", "operationId": "create_sandbox_key_sandbox_keys_post", "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/SandboxKeyCreate" }, { "type": "null" } ], "title": "Body" } } } }, "responses": { "201": { "description": "Sandbox key minted. The body is self-guiding: send `api_key` as a Bearer token, POST `example_order` to /orders as-is, and follow `next`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxKeyResponse" } } } }, "429": { "description": "Daily mint limit reached \u2014 sandbox keys are limited to a few per IP per day (plus a global cap). Reuse a key you already minted (valid until 7 days after its last use) or retry after `Retry-After` elapses.", "headers": { "Retry-After": { "description": "Seconds until the daily window resets (UTC midnight)", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp of the window reset", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Temporarily unable to mint \u2014 the sandbox or its rate limiter is unavailable (the limiter fails closed by design). Safe to retry after `Retry-After`.", "headers": { "Retry-After": { "description": "Suggested backoff in seconds", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [] } }, "/sandbox/claim": { "post": { "tags": [ "sandbox" ], "summary": "Claim a sandbox into your account", "description": "Fold a provisional sandbox into the authenticated account.\n\nAlways a merge: Stytch's callback creates a real user row on first login,\nso a caller reaching this endpoint already has an account. The agent's key\nis reassigned rather than revoked, so whatever it has hardcoded keeps\nworking \u2014 that is the point of claiming rather than starting over.", "operationId": "claim_sandbox_sandbox_claim_post", "parameters": [ { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxClaimRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxClaimResponse" } } } }, "404": { "description": "Unknown, already-used, or swept claim token. Claim tokens are single-use and die with the sandbox they belong to.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/sandbox/status": { "get": { "tags": [ "sandbox" ], "summary": "Has this sandbox been claimed?", "description": "Whether the sandbox this key belongs to has been claimed yet.\n\nAn agent hands its claim URL to a human and then has no way to learn what\nhappened \u2014 a device-code grant would tell it for free (issue #825). Until\nwe have one, polling this closes the loop.\n\nStill provisional means nobody has claimed it. Past that, \"not provisional\"\nalone would be a lie \u2014 every ordinary account would read as claimed \u2014 so\nthe answer comes from the claim event written on the account, which is\nalso the only durable evidence a claim happened once the provisional row\nis deleted.", "operationId": "get_sandbox_status_sandbox_status_get", "parameters": [ { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxStatusResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/sandbox/quickstart": { "get": { "tags": [ "sandbox" ], "summary": "Agent quickstart guide (markdown)", "description": "The agent quickstart, served as plain markdown.", "operationId": "get_quickstart_sandbox_quickstart_get", "responses": { "200": { "description": "The agent quickstart as plain markdown: mint a key, place a sandbox order, watch the lifecycle, rehearse each failure mode, go live.", "content": { "text/markdown; charset=utf-8": { "schema": { "type": "string" } } } } }, "security": [] } }, "/device/code": { "post": { "tags": [ "device" ], "summary": "Start a sign-in the account owner can approve from any device", "description": "Mint a device code. No account needed.\n\nSend your `zn_test_` sandbox key as the bearer and the sandbox comes along:\nwhen the owner approves, its orders and key move onto their account and\nyour sandbox key keeps working, alongside the live key you receive.", "operationId": "create_device_code_device_code_post", "parameters": [ { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/DeviceCodeCreate" }, { "type": "null" } ], "title": "Body" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceCodeResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/device/codes/{user_code}": { "get": { "tags": [ "device" ], "summary": "What an approval page shows for a user code", "description": "Public on purpose: it holds only what the agent said about itself, and\nthe approval page needs it before the human has signed in.", "operationId": "describe_device_code_device_codes__user_code__get", "parameters": [ { "name": "user_code", "in": "path", "required": true, "schema": { "type": "string", "title": "User Code" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceCodeInfo" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/device/approve": { "post": { "tags": [ "device" ], "summary": "Approve or deny a device code (signed-in browser only)", "description": "The human's decision. A machine credential must never make it: an API\nkey approving a device code would be a key minting a key.", "operationId": "decide_device_code_device_approve_post", "parameters": [ { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceApproveRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceApproveResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/device/token": { "post": { "tags": [ "device" ], "summary": "Poll for the key (returns it exactly once)", "operationId": "redeem_device_code_device_token_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceTokenRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyExchangeResponse" } } } }, "400": { "description": "`authorization_pending` (keep polling), `slow_down` (poll less often), or `expired_token` (start over)." }, "403": { "description": "`access_denied` \u2014 the owner declined; stop." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/webhooks/endpoint": { "get": { "tags": [ "webhooks" ], "summary": "Get Webhook Endpoint", "description": "The URL Zinc delivers this account's webhooks to, and the HMAC secret\nthat signs them. Both are null until ``PUT /webhooks/endpoint`` is called.", "operationId": "get_webhook_endpoint_webhooks_endpoint_get", "parameters": [ { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "put": { "tags": [ "webhooks" ], "summary": "Set Webhook Endpoint", "description": "Register (or replace) the webhook URL for this account.\n\nEvery order and return event Zinc emits for the account is POSTed to this\nURL. A signing secret is generated on first registration and returned so\nthe caller can verify the ``X-Webhook-Signature`` header; replacing the URL\nkeeps the existing secret, so a URL move never invalidates verification.", "operationId": "set_webhook_endpoint_webhooks_endpoint_put", "parameters": [ { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "webhooks" ], "summary": "Clear Webhook Endpoint", "description": "Stop webhook delivery for this account by clearing the URL.\n\nThe signing secret is kept, so re-registering a URL later resumes\ndeliveries signed with the same secret the caller already verifies against.", "operationId": "clear_webhook_endpoint_webhooks_endpoint_delete", "parameters": [ { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/health": { "get": { "tags": [ "health" ], "summary": "Get Public Health", "description": "Customer-facing platform health.\n\nNo auth. Cached in-process for 4 minutes \u2014 at the marketing site's 5-min\ncron cadence, the DB is touched at most ~once per tick.", "operationId": "get_public_health_health_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicHealthResponse" } } } } } } } }, "components": { "schemas": { "Address": { "properties": { "first_name": { "type": "string", "title": "First Name" }, "last_name": { "type": "string", "title": "Last Name" }, "address_line1": { "type": "string", "maxLength": 60, "title": "Address Line1", "description": "Street address. At most 60 characters \u2014 retailers reject a longer line outright rather than truncating it." }, "address_line2": { "anyOf": [ { "type": "string", "maxLength": 60 }, { "type": "null" } ], "title": "Address Line2", "description": "Apartment, suite, unit, etc. At most 60 characters \u2014 retailers reject a longer line outright rather than truncating it." }, "city": { "type": "string", "title": "City" }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "State" }, "postal_code": { "type": "string", "title": "Postal Code", "description": "Postal code. For a US address this must be a ZIP: 5 digits, optionally +4 (e.g. '98632' or '27517-8761')." }, "phone_number": { "type": "string", "title": "Phone Number" }, "country": { "type": "string", "title": "Country", "description": "Country as an ISO 3166-1 alpha-2 code (e.g. 'US', 'CA', 'GB', 'DE'). Case-insensitive. Longer spellings such as 'USA' or 'United States' are rejected \u2014 the error names the code to use.", "default": "US" } }, "type": "object", "required": [ "first_name", "last_name", "address_line1", "city", "postal_code", "phone_number" ], "title": "Address", "description": "Shipping address model.\n\nSupports international addresses. The `state` field is optional for countries\nthat don't use states/provinces. The `country` field uses ISO 3166-1 alpha-2\ncountry codes (e.g., \"US\", \"CA\", \"GB\", \"DE\"), which are required rather than\ninferred \u2014 a longer spelling like \"USA\" is rejected with the code to use, so\neverything downstream can rely on seeing alpha-2." }, "ApiKeyExchangeResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "key": { "type": "string", "title": "Key" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "is_active": { "type": "boolean", "title": "Is Active" }, "is_test": { "type": "boolean", "title": "Is Test" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "wallet_balance_cents": { "type": "integer", "title": "Wallet Balance Cents", "description": "Spendable wallet balance of the account the key belongs to." }, "sandbox": { "anyOf": [ { "$ref": "#/components/schemas/SandboxClaimSummary" }, { "type": "null" } ], "description": "What the sandbox claim moved, when `sandbox_key` was sent." }, "starter_credit": { "anyOf": [ { "$ref": "#/components/schemas/StarterCredit" }, { "type": "null" } ], "description": "Wallet credit granted alongside this key, if the account earned one, with a few items it is known to cover." }, "api_key": { "type": "string", "title": "Api Key", "readOnly": true } }, "type": "object", "required": [ "id", "key", "name", "is_active", "is_test", "created_at", "wallet_balance_cents", "api_key" ], "title": "ApiKeyExchangeResponse", "description": "The issued key, plus what the agent needs to act on it right away." }, "BulkBatchListResponse": { "properties": { "batches": { "items": { "$ref": "#/components/schemas/BulkBatchResponse" }, "type": "array", "title": "Batches" }, "total": { "type": "integer", "title": "Total" } }, "type": "object", "required": [ "total" ], "title": "BulkBatchListResponse", "description": "A user's recent bulk-upload batches (newest first)." }, "BulkBatchResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "filename": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Filename" }, "status": { "$ref": "#/components/schemas/BulkBatchStatus" }, "row_count": { "type": "integer", "title": "Row Count" }, "placed_count": { "type": "integer", "title": "Placed Count" }, "failed_count": { "type": "integer", "title": "Failed Count" }, "notify_on_complete": { "type": "boolean", "title": "Notify On Complete", "default": false }, "notified_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Notified At" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At" }, "rows": { "items": { "$ref": "#/components/schemas/BulkRowResult" }, "type": "array", "title": "Rows" } }, "type": "object", "required": [ "id", "status", "row_count", "placed_count", "failed_count", "created_at", "updated_at" ], "title": "BulkBatchResponse", "description": "A bulk-upload batch and (on the detail endpoint) its per-row results." }, "BulkBatchStatus": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ], "title": "BulkBatchStatus", "description": "Lifecycle of a CSV bulk-upload batch." }, "BulkRowResult": { "properties": { "index": { "type": "integer", "title": "Index" }, "status": { "type": "string", "title": "Status", "description": "placed | failed | pending" }, "order_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Order Id" }, "order_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Order Status" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "recipient": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Recipient" }, "product_urls": { "items": { "type": "string" }, "type": "array", "title": "Product Urls" }, "passthrough": { "additionalProperties": true, "type": "object", "title": "Passthrough" } }, "type": "object", "required": [ "index", "status" ], "title": "BulkRowResult", "description": "Per-row outcome once a batch has been (or is being) processed." }, "BulkRowValidation": { "properties": { "index": { "type": "integer", "title": "Index", "description": "Zero-based row index in the uploaded file." }, "ok": { "type": "boolean", "title": "Ok" }, "errors": { "items": { "type": "string" }, "type": "array", "title": "Errors" }, "product_urls": { "items": { "type": "string" }, "type": "array", "title": "Product Urls" }, "quantities": { "items": { "type": "integer" }, "type": "array", "title": "Quantities" }, "recipient": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Recipient" }, "destination": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Destination" }, "max_price": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Max Price" }, "retailer_credentials_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Retailer Credentials Id" }, "passthrough": { "additionalProperties": true, "type": "object", "title": "Passthrough" } }, "type": "object", "required": [ "index", "ok" ], "title": "BulkRowValidation", "description": "Per-row result of a dry-run validation." }, "BulkUploadRequest": { "properties": { "filename": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Filename", "description": "Original uploaded filename, for display." }, "rows": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Rows", "description": "Parsed CSV rows, each a mapping of column header to cell value." }, "notify_on_complete": { "type": "boolean", "title": "Notify On Complete", "description": "Email the account holder once every order in this batch has reached a terminal state (placed, failed, or cancelled).", "default": false } }, "type": "object", "title": "BulkUploadRequest", "description": "Raw CSV rows (header -> cell) posted from the dashboard." }, "BulkValidateResponse": { "properties": { "filename": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Filename" }, "total_rows": { "type": "integer", "title": "Total Rows" }, "valid_rows": { "type": "integer", "title": "Valid Rows" }, "invalid_rows": { "type": "integer", "title": "Invalid Rows" }, "estimated_total_cents": { "type": "integer", "title": "Estimated Total Cents" }, "wallet_balance_cents": { "type": "integer", "title": "Wallet Balance Cents" }, "sufficient_funds": { "type": "boolean", "title": "Sufficient Funds" }, "billed_by_invoice": { "type": "boolean", "title": "Billed By Invoice", "default": false }, "over_credit_limit": { "type": "boolean", "title": "Over Credit Limit", "default": false }, "rows": { "items": { "$ref": "#/components/schemas/BulkRowValidation" }, "type": "array", "title": "Rows" } }, "type": "object", "required": [ "total_rows", "valid_rows", "invalid_rows", "estimated_total_cents", "wallet_balance_cents", "sufficient_funds" ], "title": "BulkValidateResponse", "description": "Dry-run summary returned before any orders are placed." }, "CheckoutOrderCreate": { "properties": { "products": { "items": { "$ref": "#/components/schemas/OrderProduct" }, "type": "array", "minItems": 1, "title": "Products" }, "shipping_address": { "anyOf": [ { "$ref": "#/components/schemas/Address" }, { "type": "null" } ], "description": "Where to ship. Required for wallet and Connect orders." }, "max_price": { "type": "integer", "minimum": 0.0, "title": "Max Price", "description": "Maximum price (in cents) allowed for an order before it is finalized." }, "idempotency_key": { "anyOf": [ { "type": "string", "maxLength": 36 }, { "type": "null" } ], "title": "Idempotency Key", "description": "Optional idempotency key to prevent duplicate orders. If not provided, one will be generated." }, "retailer_credentials_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Retailer Credentials Id", "description": "Optional short ID (e.g. 'zn_acct_XXXXXXXX') of one of your own saved retailer accounts to place this order on. The item is then paid for by the payment method saved on that account, and your wallet is charged the API fee only \u2014 so the balance needed to place the order is the fee, not max_price + fee. Omit it and the order is placed on a Zinc account and funded from your wallet; Zinc never substitutes one of your saved accounts, so send this field on every order that has to run on yours." }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "Optional metadata to attach to the order. Can contain arbitrary key-value pairs." }, "po_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Po Number", "description": "Optional purchase order number for the order." }, "handling_days_max": { "anyOf": [ { "type": "integer", "minimum": 1.0 }, { "type": "null" } ], "title": "Handling Days Max", "description": "Optional ceiling on a seller's shipping and handling days. Omit or send null for no limit." }, "is_gift": { "type": "boolean", "title": "Is Gift", "description": "Mark the order as a gift, suppressing prices on the packing slip. If the retailer's checkout offers no free gift option, the order FAILS with `gift_option_unavailable` rather than being placed as a normal order \u2014 a gift that arrives with prices visible to the recipient is treated as worse than no order.", "default": false }, "gift_message": { "anyOf": [ { "type": "string", "maxLength": 240 }, { "type": "null" } ], "title": "Gift Message", "description": "Optional note for the recipient, entered into the retailer's gift-message field at checkout. Requires `is_gift` to be true. Max 240 characters. Delivered where the retailer's checkout offers a gift message; the order is still placed without it where one isn't available." }, "payment": { "anyOf": [ { "$ref": "#/components/schemas/OrderPayment" }, { "type": "null" } ], "description": "Optional payment block. Omit for prepaid-wallet billing (default)." }, "customer_notifications": { "anyOf": [ { "$ref": "#/components/schemas/CustomerNotifications" }, { "type": "null" } ], "description": "Opt in to emailing the end customer order updates (and unlock the public tracking page for this order). Adds a per-order surcharge. Omit for no customer notifications (default)." }, "fulfillment": { "anyOf": [ { "$ref": "#/components/schemas/FulfillmentPreferences" }, { "type": "null" } ], "description": "Loosen the order's strict-by-default rules. Omit for today's behaviour: any rule that can't be met fails the order. Set a rule (`gift`, `items`, `quantity`) to `best_effort` to have the order placed anyway; anything left unset stays strict. Whatever was relaxed is reported back in `fulfillment.concessions` on the order. `max_price` is never relaxed. `excluded_merchants` tightens instead: merchants this order must not be bought from." } }, "type": "object", "required": [ "products", "max_price" ], "title": "CheckoutOrderCreate", "description": "Request body for ``POST /orders``." }, "Components": { "properties": { "db": { "type": "string", "enum": [ "up", "warning", "down" ], "title": "Db" }, "queue": { "type": "string", "enum": [ "up", "warning", "down" ], "title": "Queue" }, "ordering": { "type": "string", "enum": [ "up", "warning", "down" ], "title": "Ordering" } }, "type": "object", "required": [ "db", "queue", "ordering" ], "title": "Components" }, "CoverageInfo": { "properties": { "policy": { "type": "string", "title": "Policy", "description": "'open': listed retailers are not the limit." }, "summary": { "type": "string", "title": "Summary" }, "platforms": { "items": { "$ref": "#/components/schemas/CoveragePlatform" }, "type": "array", "title": "Platforms" } }, "type": "object", "required": [ "policy", "summary" ], "title": "CoverageInfo", "description": "What the catalog does and does not tell you.\n\nSits on `GET /retailers` because that list reads as the whole answer and is\nnot: it is the curated set, while the order path accepts most stores." }, "CoveragePlatform": { "properties": { "platform": { "type": "string", "title": "Platform", "description": "Storefront platform, e.g. 'shopify'." }, "orderable": { "type": "boolean", "title": "Orderable", "description": "Zinc attempts checkout at stores on this platform, including ones it has never seen. For one store's tier, call GET /retailers/check." } }, "type": "object", "required": [ "platform", "orderable" ], "title": "CoveragePlatform", "description": "A storefront platform Zinc will attempt checkout on, sight unseen." }, "CustomerNotificationStatus": { "properties": { "email": { "type": "string", "title": "Email" }, "delivered": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Delivered" } }, "type": "object", "required": [ "email" ], "title": "CustomerNotificationStatus", "description": "End-customer email-notification status for an order.\n\nPresent only when the order opted into the notifications add-on. ``delivered``\nis the deliverability signal: True once a notification reached the shopper\n(an unsubscribe click also counts \u2014 it proves receipt), False if one was\nattempted but bounced/failed/suppressed, and null while nothing has been\nsent yet (e.g. not shipped) or a send is still in flight." }, "CustomerNotifications": { "properties": { "email": { "type": "string", "format": "email", "title": "Email", "description": "End-customer email address to send order updates to." } }, "type": "object", "required": [ "email" ], "title": "CustomerNotifications", "description": "Opt-in to email the END customer as this order progresses.\n\nProviding this block opts the order into the notifications add-on: a\nper-order surcharge is applied and the public tracking page becomes\nreachable for the order. The feature is gated server-side by\n``customer_emails_enabled``; while that's off the block has no effect." }, "DeliveryMapPoint": { "properties": { "lat": { "type": "number", "title": "Lat" }, "long": { "type": "number", "title": "Long" }, "emoji": { "type": "string", "title": "Emoji" } }, "type": "object", "required": [ "lat", "long", "emoji" ], "title": "DeliveryMapPoint", "description": "One delivered-order marker for the marketing site's globe.\n\nCoordinates are a ZIP centroid rounded to two decimals \u2014 never a street\naddress, but the rounding does not hide which ZIP (see\n``lib.routers.stats``). Deliberately carries no order id, name, address,\nor per-point timestamp." }, "DeliveryMapResponse": { "properties": { "points": { "items": { "$ref": "#/components/schemas/DeliveryMapPoint" }, "type": "array", "title": "Points" }, "window_days": { "type": "integer", "title": "Window Days" }, "generated_at": { "type": "string", "format": "date-time", "title": "Generated At" } }, "type": "object", "required": [ "points", "window_days", "generated_at" ], "title": "DeliveryMapResponse", "description": "Recent delivered orders as deduplicated, anonymized map points." }, "DeviceApproveRequest": { "properties": { "user_code": { "type": "string", "maxLength": 16, "minLength": 4, "title": "User Code" }, "granted": { "type": "boolean", "title": "Granted" } }, "type": "object", "required": [ "user_code", "granted" ], "title": "DeviceApproveRequest" }, "DeviceApproveResponse": { "properties": { "status": { "type": "string", "title": "Status" }, "name": { "type": "string", "title": "Name" }, "message": { "type": "string", "title": "Message" } }, "type": "object", "required": [ "status", "name", "message" ], "title": "DeviceApproveResponse" }, "DeviceCodeCreate": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "title": "Name", "description": "What to call yourself on the approval screen and as the key's label, e.g. 'Claude Code' or 'acme-restock-agent'." } }, "type": "object", "title": "DeviceCodeCreate" }, "DeviceCodeInfo": { "properties": { "user_code": { "type": "string", "title": "User Code" }, "name": { "type": "string", "title": "Name" }, "source": { "type": "string", "title": "Source", "description": "Runtime guessed from the requesting User-Agent (claude-code, codex, curl, \u2026)." }, "sandbox_attached": { "type": "boolean", "title": "Sandbox Attached", "description": "Approval will also claim the agent's sandbox into the approving account." }, "starter_credit_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Starter Credit Cents", "description": "Wallet credit approval would add, when the attached sandbox has placed an order and the account has not had one; null otherwise." }, "status": { "type": "string", "title": "Status", "description": "pending | approved | denied" } }, "type": "object", "required": [ "user_code", "name", "source", "sandbox_attached", "status" ], "title": "DeviceCodeInfo", "description": "What the approval page shows before the human decides. Public: it holds\nonly what the agent chose to say about itself." }, "DeviceCodeResponse": { "properties": { "device_code": { "type": "string", "title": "Device Code", "description": "Your half of the handshake. Keep it; send it when polling. Never show it to the human." }, "user_code": { "type": "string", "title": "User Code", "description": "The short code the human sees on the approval page." }, "verification_uri": { "type": "string", "title": "Verification Uri", "description": "Where the human approves; they will be asked for `user_code`." }, "verification_uri_complete": { "type": "string", "title": "Verification Uri Complete", "description": "Same page with the code filled in. Show this one." }, "expires_in": { "type": "integer", "title": "Expires In", "description": "Seconds until this code stops working." }, "interval": { "type": "integer", "title": "Interval", "description": "Minimum seconds between polls of POST /device/token." }, "human_message": { "type": "string", "title": "Human Message", "description": "One sentence to show your operator, ready to paste." }, "next": { "type": "string", "title": "Next", "description": "What to do now." } }, "type": "object", "required": [ "device_code", "user_code", "verification_uri", "verification_uri_complete", "expires_in", "interval", "human_message", "next" ], "title": "DeviceCodeResponse" }, "DeviceTokenRequest": { "properties": { "device_code": { "type": "string", "maxLength": 128, "minLength": 16, "title": "Device Code" } }, "type": "object", "required": [ "device_code" ], "title": "DeviceTokenRequest" }, "ErrorCode": { "type": "string", "enum": [ "unauthorized", "forbidden", "invalid_token", "token_expired", "not_found", "already_exists", "validation_error", "insufficient_funds", "authorization_pending", "slow_down", "expired_token", "access_denied", "payment_failed", "payment_method_required", "payment_required", "invalid_payment_method", "invalid_shipping_address", "url_unreachable", "non_us_retailer", "unsupported_retailer", "unsupported_country", "retailer_country_not_supported", "guest_checkout_not_supported", "invalid_variant", "out_of_stock", "shipping_unavailable", "order_not_cancellable", "return_not_allowed", "external_service_error", "stripe_error", "stytch_error", "internal_error", "bad_request", "rate_limit_exceeded", "service_unavailable" ], "title": "ErrorCode", "description": "Standardized error codes for the API." }, "ErrorDetail": { "properties": { "code": { "$ref": "#/components/schemas/ErrorCode" }, "message": { "type": "string", "title": "Message" }, "details": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Details" } }, "type": "object", "required": [ "code", "message" ], "title": "ErrorDetail", "description": "Standard error response body." }, "ErrorDetails": { "properties": { "code": { "type": "string", "title": "Code" }, "message": { "type": "string", "title": "Message" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url" }, "address_validation_reasons": { "items": { "type": "string" }, "type": "array", "title": "Address Validation Reasons", "default": [] }, "field_errors": { "items": { "$ref": "#/components/schemas/FieldError" }, "type": "array", "title": "Field Errors", "default": [] }, "line_rejections": { "items": { "$ref": "#/components/schemas/LineRejection" }, "type": "array", "title": "Line Rejections", "default": [] } }, "additionalProperties": true, "type": "object", "required": [ "code", "message" ], "title": "ErrorDetails", "description": "Structured detail for a failed job.\n\nAdditive sibling to the flat `error`/`error_type` keys (kept for\nback-compat). The structured home for enrichment beyond the category +\nmessage \u2014 e.g. why a shipping address was rejected \u2014 so we don't keep\ngrowing loose top-level keys on the job output." }, "ErrorResponse": { "properties": { "error": { "$ref": "#/components/schemas/ErrorDetail" } }, "type": "object", "required": [ "error" ], "title": "ErrorResponse", "description": "Wrapper for error responses." }, "FieldError": { "properties": { "field": { "type": "string", "title": "Field" }, "code": { "type": "string", "title": "Code" }, "message": { "type": "string", "title": "Message", "default": "" }, "received": { "title": "Received" }, "expected": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Expected" } }, "additionalProperties": true, "type": "object", "required": [ "field", "code" ], "title": "FieldError", "description": "A single field-level validation failure from a worker.\n\nWhen a job fails schema\nvalidation the worker reports one of these per offending field, so consumers\ncan show \"state should be 'NY', got 'New York'\" instead of a bare count." }, "FulfillmentConcession": { "properties": { "concern": { "type": "string", "enum": [ "gift", "items", "quantity" ], "title": "Concern" }, "code": { "type": "string", "title": "Code", "description": "Worker error code that would have failed a strict order." }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Message" }, "item_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Item Id", "description": "Order item this concession is about, if any." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url" }, "requested_quantity": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Requested Quantity" }, "fulfilled_quantity": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Fulfilled Quantity" } }, "additionalProperties": true, "type": "object", "required": [ "concern", "code" ], "title": "FulfillmentConcession", "description": "One rule that was actually relaxed while placing the order." }, "FulfillmentMode": { "type": "string", "enum": [ "best_effort" ], "title": "FulfillmentMode", "description": "How hard to hold one order rule \u2014 the value of a ``fulfillment`` key\n(``fulfillment.items: \"best_effort\"``).\n\nEvery mode loosens; strict is the *absence* of a mode, never a spelling of\none. A future softer mode for a concern (``prefer``, ``nearest``) is a new\nmember here; a future per-concern knob is that concern's value growing from\na bare mode into an object \u2014 neither is a new top-level order field." }, "FulfillmentPreferences": { "properties": { "gift": { "anyOf": [ { "$ref": "#/components/schemas/FulfillmentMode" }, { "type": "null" } ], "description": "`best_effort`: if the retailer offers no free gift option, place a normal order instead of failing with `gift_option_unavailable`. Requires `is_gift: true`. Omit to keep the gift requirement strict." }, "items": { "anyOf": [ { "$ref": "#/components/schemas/FulfillmentMode" }, { "type": "null" } ], "description": "`best_effort`: if an item can't be bought (not found, out of stock, variant or condition unavailable, add-to-cart failed), skip it and ship the rest \u2014 its status becomes `skipped`. An empty cart still fails. Omit for all-or-nothing." }, "quantity": { "anyOf": [ { "$ref": "#/components/schemas/FulfillmentMode" }, { "type": "null" } ], "description": "`best_effort`: if the retailer caps an item below the requested quantity, buy the cap instead of failing with `quantity_limit_exceeded`. Omit to require the full quantity." }, "excluded_merchants": { "anyOf": [ { "items": { "type": "string" }, "type": "array", "maxItems": 20 }, { "type": "null" } ], "title": "Excluded Merchants", "description": "Merchants this order must never be bought from: a display name as shown on the retailer's storefront (matched ignoring case and spacing) or an Amazon Business `amzn1.` merchant id. At most 20 entries. Added to any blocklist already on your account; it can only bar more merchants, never allow a barred one. Currently applied to Amazon Business orders only and ignored elsewhere." } }, "additionalProperties": false, "type": "object", "title": "FulfillmentPreferences", "description": "Which strict order rules may be relaxed. The order contract is strict by\ndefault; this object only ever loosens it.\n\nOne key per concern \u2014 ``gift``, ``items``, ``quantity`` \u2014 whose value is the\nmode to hold that rule at. Absent (or null) is today's behaviour, so an\nomitted block and ``{}`` mean the same strict order. There is deliberately\nno ``\"strict\"`` mode to write \u2014 the existing fields already mean that\n(``is_gift: true`` is a required gift; a products list is all-or-nothing),\nand a second spelling of the same intent is a second thing to get wrong.\nUnknown keys and unknown modes are rejected rather than ignored, so a typo\ncan never silently mean \"strict\".\n\nExtension point: a softer mode for a concern is a new ``FulfillmentMode``\nmember (``prefer``, ``nearest``); a per-concern knob is that concern's value\nwidening from a bare mode into an object (``items: {mode: \"best_effort\",\nmin_items: 2}``) \u2014 never a new top-level order field.\n\nThe one exception to \"only loosens\" is ``excluded_merchants``: a per-order\nseller blocklist, here rather than top-level because it is rare and only\nsome placement paths can honour it (BizAPI today; ignored elsewhere). It is\nnot a ``FulfillmentConcern`` and never produces a concession." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "LifetimeStatsResponse": { "properties": { "orders_successful": { "type": "integer", "title": "Orders Successful" }, "gmv_cents": { "type": "integer", "title": "Gmv Cents" }, "v2_as_of": { "type": "string", "format": "date-time", "title": "V2 As Of" }, "v1": { "$ref": "#/components/schemas/LifetimeV1Stats" }, "combined": { "$ref": "#/components/schemas/LifetimeTotals" } }, "type": "object", "required": [ "orders_successful", "gmv_cents", "v2_as_of", "v1", "combined" ], "title": "LifetimeStatsResponse", "description": "Zinc's all-time order and GMV totals.\n\nTop-level ``orders_successful`` / ``gmv_cents`` are the v2 (this service's)\nnumbers, live as of ``v2_as_of``; ``v1`` is the seeded legacy snapshot;\n``combined`` is the convenience sum of both." }, "LifetimeTotals": { "properties": { "orders_successful": { "type": "integer", "title": "Orders Successful" }, "gmv_cents": { "type": "integer", "title": "Gmv Cents" } }, "type": "object", "required": [ "orders_successful", "gmv_cents" ], "title": "LifetimeTotals", "description": "Combined v1 + v2 all-time totals." }, "LifetimeV1Stats": { "properties": { "orders_successful": { "type": "integer", "title": "Orders Successful" }, "gmv_cents": { "type": "integer", "title": "Gmv Cents" }, "as_of": { "type": "string", "format": "date", "title": "As Of" }, "source": { "type": "string", "enum": [ "seeded", "computed" ], "title": "Source", "default": "seeded" } }, "type": "object", "required": [ "orders_successful", "gmv_cents", "as_of" ], "title": "LifetimeV1Stats", "description": "All-time totals from the legacy v1 API (api.zinc.io).\n\n``source: \"computed\"`` \u2014 read from the snapshot the weekly worker job\nstores (see ``lib.tasks.v1_lifetime``); ``source: \"seeded\"`` \u2014 the\nin-code cold-start fallback constant." }, "LineRejection": { "properties": { "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url" }, "product_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Product Id" }, "requested_quantity": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Requested Quantity" }, "available_quantity": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Available Quantity" }, "codes": { "items": { "type": "string" }, "type": "array", "title": "Codes", "default": [] }, "messages": { "items": { "type": "string" }, "type": "array", "title": "Messages", "default": [] } }, "type": "object", "title": "LineRejection", "description": "One order line the retailer rejected, as it reported it (BizAPI)." }, "MarginSpec": { "properties": { "type": { "type": "string", "enum": [ "flat", "percent" ], "title": "Type" }, "value": { "type": "number", "minimum": 0.0, "title": "Value", "description": "Cents when type='flat'; a percentage when type='percent' (e.g. 15 == 15%)." } }, "type": "object", "required": [ "type", "value" ], "title": "MarginSpec", "description": "Customer's markup on the order cost (computed before fees)." }, "OrderCartItem": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "product_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Product Id", "description": "Retailer product identifier (Amazon ASIN, Walmart item number, SKU) when one is visible on the page. Often absent \u2014 do not rely on it to join rows back to the requested products." }, "quantity": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Quantity" }, "unit_price": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Unit Price", "description": "Price per unit." }, "line_total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Line Total", "description": "Total for this row, normally `quantity * unit_price`. May differ when the retailer applies a per-line promotion." } }, "additionalProperties": true, "type": "object", "title": "OrderCartItem", "description": "A single product row from the retailer's cart or order summary.\n\nLenient and open (``extra=\"allow\"``) like its siblings \u2014 it mirrors\nfulfillment output that may be partial. All amounts are in cents." }, "OrderConnectInfo": { "properties": { "state": { "type": "string", "title": "State", "description": "secured | captured | released | refunded | \u2026" }, "secured_amount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Secured Amount" }, "order_cost": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Order Cost", "description": "Actual order cost (goods) captured when the order is placed." }, "customer_margin": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Customer Margin" }, "zinc_fee": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Zinc Fee" }, "stripe_fee": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Stripe Fee" }, "final_charge": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Final Charge" }, "transfer_amount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Transfer Amount" }, "payment_intent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Payment Intent Id" }, "connected_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Connected Account Id" }, "simulated": { "type": "boolean", "title": "Simulated", "default": false } }, "type": "object", "required": [ "state" ], "title": "OrderConnectInfo", "description": "Stripe Connect charge + state for an order paid via Connect. Present only\nwhen the order has a Connect profile; ``null`` for prepaid-wallet orders. All\namounts in cents.\n\n``state`` moves ``secured`` \u2192 ``captured`` (or ``released``/``refunded`` on a\nterminal outcome). The post-capture fields (``order_cost`` and below) are\npopulated once Zinc places the order with the retailer and the actual total\nis captured." }, "OrderFulfillment": { "properties": { "gift": { "anyOf": [ { "$ref": "#/components/schemas/FulfillmentMode" }, { "type": "null" } ], "description": "`best_effort`: if the retailer offers no free gift option, place a normal order instead of failing with `gift_option_unavailable`. Requires `is_gift: true`. Omit to keep the gift requirement strict." }, "items": { "anyOf": [ { "$ref": "#/components/schemas/FulfillmentMode" }, { "type": "null" } ], "description": "`best_effort`: if an item can't be bought (not found, out of stock, variant or condition unavailable, add-to-cart failed), skip it and ship the rest \u2014 its status becomes `skipped`. An empty cart still fails. Omit for all-or-nothing." }, "quantity": { "anyOf": [ { "$ref": "#/components/schemas/FulfillmentMode" }, { "type": "null" } ], "description": "`best_effort`: if the retailer caps an item below the requested quantity, buy the cap instead of failing with `quantity_limit_exceeded`. Omit to require the full quantity." }, "excluded_merchants": { "anyOf": [ { "items": { "type": "string" }, "type": "array", "maxItems": 20 }, { "type": "null" } ], "title": "Excluded Merchants", "description": "Merchants this order must never be bought from: a display name as shown on the retailer's storefront (matched ignoring case and spacing) or an Amazon Business `amzn1.` merchant id. At most 20 entries. Added to any blocklist already on your account; it can only bar more merchants, never allow a barred one. Currently applied to Amazon Business orders only and ignored elsewhere." }, "concessions": { "items": { "$ref": "#/components/schemas/FulfillmentConcession" }, "type": "array", "title": "Concessions", "default": [] } }, "type": "object", "title": "OrderFulfillment", "description": "What was asked (the per-concern modes, all null on a strict order) plus\nwhat was actually relaxed (``concessions``, empty when the order was\nfulfilled exactly as requested \u2014 which is every strict order)." }, "OrderItemResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "url": { "type": "string", "title": "Url" }, "quantity": { "type": "integer", "title": "Quantity" }, "variant": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ProductVariant" }, "type": "array" }, { "type": "null" } ], "title": "Variant" }, "condition_in": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ProductCondition" }, "type": "array" }, { "type": "null" } ], "title": "Condition In" }, "condition_not_in": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ProductCondition" }, "type": "array" }, { "type": "null" } ], "title": "Condition Not In" }, "status": { "$ref": "#/components/schemas/OrderItemStatus" }, "cancellation_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cancellation Reason" }, "error_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error Type" }, "tracking_number_ids": { "anyOf": [ { "items": { "type": "string", "format": "uuid" }, "type": "array" }, { "type": "null" } ], "title": "Tracking Number Ids", "description": "Ids of the `tracking_numbers[]` known to carry this item, best effort. Null when unknown (never an empty list). The reverse of `tracking_numbers[].order_item_ids`." }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At" } }, "type": "object", "required": [ "id", "url", "quantity", "status", "created_at", "updated_at" ], "title": "OrderItemResponse", "description": "Response model for order item data.\n\nField names mirror the OrderItem model, so callers build it with\n``OrderItemResponse.model_validate(item)`` rather than enumerating fields." }, "OrderItemStatus": { "type": "string", "enum": [ "pending", "processing", "ordered", "shipped", "available_for_pickup", "delivered", "cancelled", "failed", "skipped" ], "title": "OrderItemStatus" }, "OrderJobResult": { "properties": { "success": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Success" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "error_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error Type" }, "error_details": { "anyOf": [ { "$ref": "#/components/schemas/ErrorDetails" }, { "type": "null" } ] }, "price_components": { "anyOf": [ { "$ref": "#/components/schemas/OrderPriceComponents" }, { "type": "null" } ] }, "estimated_delivery": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Estimated Delivery" }, "merchant_order_ids": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Merchant Order Ids" } }, "additionalProperties": true, "type": "object", "title": "OrderJobResult", "description": "Fulfillment result surfaced on a completed or failed order. Null while the\norder is still processing.\n\nLenient and open (``extra=\"allow\"``) so it documents the common fields \u2014\nsuccess, price breakdown, errors, merchant order ids, delivery estimate \u2014\nwithout constraining the full processing payload, which carries additional\ninternal detail." }, "OrderListResponse": { "properties": { "orders": { "items": { "$ref": "#/components/schemas/OrderResponse" }, "type": "array", "title": "Orders" }, "total": { "type": "integer", "title": "Total" }, "limit": { "type": "integer", "title": "Limit" }, "offset": { "type": "integer", "title": "Offset" } }, "type": "object", "required": [ "orders", "total", "limit", "offset" ], "title": "OrderListResponse", "description": "List of orders for a particular user_id" }, "OrderMilestone": { "properties": { "type": { "type": "string", "enum": [ "order_created", "order_placed", "tracking_acquired", "shipped", "available_for_pickup", "delivered", "undeliverable", "order_failed", "cancelled" ], "title": "Type" }, "label": { "type": "string", "title": "Label" }, "occurred_at": { "type": "string", "format": "date-time", "title": "Occurred At" }, "source": { "type": "string", "title": "Source" }, "detail": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Detail" } }, "type": "object", "required": [ "type", "label", "occurred_at", "source" ], "title": "OrderMilestone", "description": "A single point on the customer-facing order timeline." }, "OrderPayment": { "properties": { "mode": { "type": "string", "enum": [ "wallet", "card", "connect" ], "title": "Mode", "default": "wallet" }, "payment_method": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Payment Method", "description": "Connect mode: the end-customer's vaulted payment-method id on the connected account. Required for connect mode." }, "customer": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Customer", "description": "Connect mode: the end-customer's Stripe Customer id (cus_\u2026) on the connected account. Required to charge a *reusable* saved card off-session; omit only for a one-time, unattached payment method." }, "margin": { "anyOf": [ { "$ref": "#/components/schemas/MarginSpec" }, { "type": "null" } ], "description": "Connect mode: the customer's margin on the order." } }, "type": "object", "title": "OrderPayment", "description": "Optional payment block. Absent or mode='wallet' draws the order from the\nprepaid wallet. mode='connect' charges the end-customer's saved card through\nStripe Connect and keeps your margin (see ConnectService)." }, "OrderPaymentInfo": { "properties": { "mode": { "type": "string", "const": "card", "title": "Mode", "default": "card" }, "state": { "type": "string", "title": "State", "description": "authorized | captured | released | refunded | \u2026" }, "authorized_cents": { "type": "integer", "title": "Authorized Cents" }, "fee_cents": { "type": "integer", "title": "Fee Cents" }, "stripe_fee_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Stripe Fee Cents", "description": "Card-processing fee grossed into the amount above, the same way a wallet top-up and a Connect charge gross it in." }, "captured_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Captured Cents" }, "payment_method": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Payment Method" }, "payment_intent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Payment Intent Id" }, "simulated": { "type": "boolean", "title": "Simulated", "default": false } }, "type": "object", "required": [ "state", "authorized_cents", "fee_cents" ], "title": "OrderPaymentInfo", "description": "Card hold details for an order paid by card outside the wallet and\nConnect, and where that hold stands. ``null`` for wallet and Connect orders\n(Connect has its own ``connect`` block). All amounts in cents.\n\n``state`` moves ``authorized`` \u2192 ``captured`` when the retailer order is\nplaced (``captured_cents`` = actual total + fee), or \u2192 ``released`` when the\norder fails or is cancelled first. The card is only ever charged\n``captured_cents``; the difference to ``authorized_cents`` is released." }, "OrderPriceComponents": { "properties": { "subtotal": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Subtotal" }, "tax": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Tax" }, "shipping": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Shipping" }, "discount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Discount", "description": "Promotion/free-shipping discount applied by the retailer, as a positive magnitude subtracted from the total. A nonzero `shipping` paired with an equal `discount` means shipping was itemized but waived \u2014 the total correctly excludes it." }, "fees": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Fees", "description": "Retailer fees not folded into subtotal/shipping/tax (gift wrap, import/regulatory charges), as a positive magnitude added to the total. Surfaced so a total exceeding the shown parts reads as an itemized fee rather than an unexplained charge." }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total", "description": "Order total in `currency` (subtotal + tax + shipping + fees \u2212 discount)." }, "converted_payment_total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Converted Payment Total", "description": "`total` converted to `payment_currency`, the currency actually charged. On an order billed in USD from a non-USD `currency`, this is the USD amount charged, including the FX markup; `total` stays in the retailer's currency. Equal to `total` when no conversion was charged." }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Currency" }, "payment_currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Payment Currency" }, "cart_items": { "anyOf": [ { "items": { "$ref": "#/components/schemas/OrderCartItem" }, "type": "array" }, { "type": "null" } ], "title": "Cart Items", "description": "Per-product rows making up `subtotal`. Distinct from `line_items`, which carries order-level adjustments (discounts, fees) and shares no fields with these \u2014 a discount is never a cart row. Null when the retailer's checkout page did not expose readable line items, so handle both `null` and `[]`. Individual fields may also be null on a row we could only partly read. Best-effort: `sum(line_total)` normally equals `subtotal`, but that is not guaranteed and must not be used as a billing input \u2014 the charge is always driven by `total`." }, "line_items": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Line Items", "description": "Order-level adjustments, each `{description, amount, category}`. Null \u2014 not `[]` \u2014 when the producer didn't supply them, which is every BizAPI-placed order today, so null-check before iterating." }, "breakdown_recorded": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Breakdown Recorded", "description": "False when `subtotal`/`tax`/`shipping` are placeholders rather than observed figures \u2014 an order an operator recorded by hand without itemizing the whole of what they paid. Those fields read `0` in that case, which must NOT be shown as '$0.00 tax': nothing was recorded. `total` is authoritative either way. Null on results written before this flag existed; treat null as true." } }, "additionalProperties": true, "type": "object", "title": "OrderPriceComponents", "description": "Retailer price breakdown for an order, all amounts in cents.\n\nLenient by design \u2014 every field is optional and unknown keys are preserved\n(``extra=\"allow\"``) \u2014 because it mirrors fulfillment output that may be\npartial (e.g. a failed order) or carry extra detail. Documents the common\nfields without revalidating the raw payload." }, "OrderProduct": { "properties": { "url": { "type": "string", "title": "Url", "examples": [ "https://www.amazon.com/dp/B07JGBW826" ] }, "quantity": { "type": "integer", "maximum": 100.0, "minimum": 1.0, "title": "Quantity", "default": 1 }, "variant": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ProductVariant" }, "type": "array" }, { "type": "null" } ], "title": "Variant", "description": "Product variants to select (e.g., color, size)" }, "condition_in": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ProductCondition" }, "type": "array" }, { "type": "null" } ], "title": "Condition In", "description": "Condition allowlist. The agent only buys an offer whose condition is in this list. Each value must be a canonical condition. Omit or send null/[] for no constraint." }, "condition_not_in": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ProductCondition" }, "type": "array" }, { "type": "null" } ], "title": "Condition Not In", "description": "Condition denylist. The agent will not buy an offer whose condition is in this list. Each value must be a canonical condition. Omit or send null/[] for no constraint." } }, "type": "object", "required": [ "url" ], "title": "OrderProduct", "description": "Product item for an order.\n\nFor example:\n````{\n url: \"https://www.amazon.com/dp/B07JGBW826\",\n quantity: 1\n}```" }, "OrderResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "status": { "$ref": "#/components/schemas/OrderStatus" }, "max_price": { "type": "integer", "title": "Max Price" }, "attempts": { "type": "integer", "title": "Attempts" }, "items": { "items": { "$ref": "#/components/schemas/OrderItemResponse" }, "type": "array", "title": "Items" }, "shipping_address": { "additionalProperties": true, "type": "object", "title": "Shipping Address" }, "metadata": { "additionalProperties": true, "type": "object", "title": "Metadata", "default": {} }, "po_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Po Number" }, "handling_days_max": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Handling Days Max" }, "is_gift": { "type": "boolean", "title": "Is Gift", "default": false }, "gift_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Gift Message" }, "retailer_credentials_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Retailer Credentials Id" }, "retailer_credentials_uuid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Retailer Credentials Uuid" }, "job_result": { "anyOf": [ { "$ref": "#/components/schemas/OrderJobResult" }, { "type": "null" } ], "description": "Fulfillment result and price breakdown for a completed or failed order; null while processing." }, "merchant_order_ids": { "items": { "type": "string" }, "type": "array", "title": "Merchant Order Ids", "description": "The retailer's own order number(s) for this order (e.g. an Amazon `113-\u2026` ID), as recorded when it was placed. Empty while processing, or if the order never reached the retailer.", "default": [] }, "tracking_numbers": { "items": { "$ref": "#/components/schemas/TrackingNumberResponse" }, "type": "array", "title": "Tracking Numbers", "default": [] }, "created_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created By" }, "user_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "User Id" }, "returns": { "items": { "$ref": "#/components/schemas/ReturnRequestSummary" }, "type": "array", "title": "Returns", "default": [] }, "connect": { "anyOf": [ { "$ref": "#/components/schemas/OrderConnectInfo" }, { "type": "null" } ], "description": "Stripe Connect charge details when this order was paid via Connect; null for prepaid-wallet orders." }, "payment": { "anyOf": [ { "$ref": "#/components/schemas/OrderPaymentInfo" }, { "type": "null" } ], "description": "Card hold details when this order was paid by card outside the wallet and Connect; null for wallet and Connect orders." }, "customer_notifications": { "anyOf": [ { "$ref": "#/components/schemas/CustomerNotificationStatus" }, { "type": "null" } ], "description": "End-customer email-notification status when the order opted into the notifications add-on; null when it didn't." }, "fulfillment": { "$ref": "#/components/schemas/OrderFulfillment", "description": "`gift`/`items`/`quantity`: the mode this order asked for on each rule (all null = strict). `concessions`: every rule that actually was relaxed, with the worker's code and the item it concerned. Empty concessions means the order was fulfilled exactly as requested." }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At" } }, "type": "object", "required": [ "id", "status", "max_price", "attempts", "items", "shipping_address", "retailer_credentials_id", "created_at", "updated_at" ], "title": "OrderResponse", "description": "Response model for order data." }, "OrderStatus": { "type": "string", "enum": [ "pending", "in_progress", "order_placed", "order_failed", "cancelled", "cancelled_by_retailer" ], "title": "OrderStatus" }, "OrderTimelineResponse": { "properties": { "order_id": { "type": "string", "format": "uuid", "title": "Order Id" }, "current_status": { "$ref": "#/components/schemas/OrderStatus" }, "milestones": { "items": { "$ref": "#/components/schemas/OrderMilestone" }, "type": "array", "title": "Milestones" } }, "type": "object", "required": [ "order_id", "current_status", "milestones" ], "title": "OrderTimelineResponse", "description": "Customer-facing lifecycle timeline for an order.\n\nDerived on read by merging placement logs (OrderLog) with carrier tracking\nstate (TrackingNumber / TrackingCheckpoint). No dedicated storage \u2014 works\nretroactively on every historical order." }, "ProductCondition": { "type": "string", "enum": [ "New", "Refurbished", "UsedLikeNew", "UsedVeryGood", "UsedGood", "UsedAcceptable" ], "title": "ProductCondition", "description": "Canonical product-condition strings for condition filtering.\n\nMatching against ``condition_in`` / ``condition_not_in`` is exact and\ncase-sensitive against these *values*. The vocabulary matches the Zinc v1\nAPI's ``seller_selection_criteria`` condition strings." }, "ProductSearchResponse": { "properties": { "status": { "type": "string", "title": "Status" }, "results": { "items": { "$ref": "#/components/schemas/ProductSearchResult" }, "type": "array", "title": "Results", "default": [] }, "next_page": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Next Page", "description": "Only set on free_shipping searches: the page to request to keep paging. An empty `results` with a non-null next_page is NOT the end of results \u2014 request next_page to continue. None means results are exhausted (or the search was unfiltered)." } }, "type": "object", "required": [ "status" ], "title": "ProductSearchResponse", "description": "Response from the product search endpoint." }, "ProductSearchResult": { "properties": { "product_id": { "type": "string", "title": "Product Id" }, "title": { "type": "string", "title": "Title" }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Image" }, "brand": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Brand" }, "price": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Price" }, "stars": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Stars" }, "num_reviews": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Num Reviews" }, "num_offers_estimate": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Num Offers Estimate" }, "num_sales": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Num Sales" }, "product_details": { "anyOf": [ { "items": {}, "type": "array" }, { "type": "null" } ], "title": "Product Details" }, "fresh": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Fresh" }, "prime": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Prime" }, "pantry": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Pantry" }, "addon": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Addon" }, "ship_price": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Ship Price" }, "upc": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Upc" }, "mpn": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Mpn" }, "available": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Available" }, "available_online": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Available Online" }, "available_instore": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Available Instore" }, "freight_shipping": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Freight Shipping" }, "preorder": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Preorder" }, "first_party_seller": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "First Party Seller" }, "buyapi_hint": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Buyapi Hint" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url" }, "variant_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Variant Id" }, "currency_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Currency Code" } }, "type": "object", "required": [ "product_id", "title" ], "title": "ProductSearchResult", "description": "Normalized product search result across retailers.\n\nCommon fields are required or have defaults; retailer-specific fields are optional." }, "ProductVariant": { "properties": { "label": { "type": "string", "minLength": 1, "title": "Label", "description": "Variant label (e.g., 'Color', 'Size')" }, "value": { "type": "string", "minLength": 1, "title": "Value", "description": "Variant value (e.g., 'Black', 'Large')" } }, "type": "object", "required": [ "label", "value" ], "title": "ProductVariant", "description": "Product variant schema for selecting product options (color, size, etc.)." }, "PublicHealthResponse": { "properties": { "status": { "type": "string", "enum": [ "up", "warning", "down" ], "title": "Status" }, "components": { "$ref": "#/components/schemas/Components" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At" } }, "type": "object", "required": [ "status", "components", "updated_at" ], "title": "PublicHealthResponse" }, "PublicRetailer": { "properties": { "retailer": { "type": "string", "title": "Retailer", "description": "Stable retailer identifier / slug, e.g. 'amazon'." }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Display Name", "description": "Human-friendly name, e.g. 'Amazon'." }, "base_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Base Url", "description": "Retailer domain, e.g. 'amazon.com'." }, "no_account_needed": { "type": "boolean", "title": "No Account Needed", "description": "Whether Zinc can place the order for you without your own account (guest checkout or Zinc-managed credentials).", "default": false }, "use_your_account": { "type": "boolean", "title": "Use Your Account", "description": "Whether you can order through your own retailer account.", "default": false }, "supported_countries": { "items": { "type": "string" }, "type": "array", "title": "Supported Countries", "description": "ISO 3166-1 alpha-2 countries this retailer has declared it ships to. Empty = no declared restriction." }, "free_shipping": { "type": "boolean", "title": "Free Shipping", "description": "Whether free shipping is offered (unconditionally or above free_shipping_threshold_cents).", "default": false }, "free_shipping_threshold_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Free Shipping Threshold Cents", "description": "Order subtotal (cents) at/above which shipping is free; null means no threshold." }, "support": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Support", "description": "How well Zinc covers this brand: verified / active / observed. Never `unsupported` \u2014 a storefront Zinc refuses is not listed at all \u2014 so every entry here is orderable, and so are most stores that are not listed (see `coverage` and GET /retailers/check). Additive; the other fields are unchanged." } }, "type": "object", "required": [ "retailer" ], "title": "PublicRetailer", "description": "A supported retailer in the public catalog \u2014 one flat object per brand.\n\nThis is the customer-facing \"what do you support?\" shape: a retailer\nidentifier, where to buy from, the countries we ship to, the free-shipping\npolicy, and how orders are fulfilled (Zinc-managed vs. bring-your-own\naccount). Internal guest-checkout/credential details remain omitted." }, "PublicRetailerListResponse": { "properties": { "retailers": { "items": { "$ref": "#/components/schemas/PublicRetailer" }, "type": "array", "title": "Retailers" }, "total": { "type": "integer", "title": "Total" }, "coverage": { "anyOf": [ { "$ref": "#/components/schemas/CoverageInfo" }, { "type": "null" } ], "description": "States that the list is the curated set, not the limit of what Zinc can buy from. Additive; existing fields are unchanged." } }, "type": "object", "required": [ "retailers", "total" ], "title": "PublicRetailerListResponse", "description": "Public supported-retailer catalog." }, "PublicTrackingDestination": { "properties": { "address_line1": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Address Line1" }, "address_line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Address Line2" }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "City" }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "State" }, "postal_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Postal Code" }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Country" } }, "type": "object", "title": "PublicTrackingDestination", "description": "Where an order is headed, for the public tracking page.\n\nDeliberately omits the recipient's name and phone number \u2014 everything else\non the shipping address (street, city, state, ZIP, country) is shown." }, "PublicTrackingItem": { "properties": { "url": { "type": "string", "title": "Url" }, "quantity": { "type": "integer", "title": "Quantity" }, "variant": { "anyOf": [ { "items": {}, "type": "array" }, { "type": "null" } ], "title": "Variant" }, "status": { "$ref": "#/components/schemas/OrderItemStatus" } }, "type": "object", "required": [ "url", "quantity", "status" ], "title": "PublicTrackingItem", "description": "An ordered item shown on the public tracking page." }, "PublicTrackingResponse": { "properties": { "order_id": { "type": "string", "format": "uuid", "title": "Order Id" }, "current_status": { "$ref": "#/components/schemas/OrderStatus" }, "estimated_delivery_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Estimated Delivery Date", "description": "Best-known order-level delivery estimate (destination-local calendar date); per-package estimates are on each shipment." }, "destination": { "$ref": "#/components/schemas/PublicTrackingDestination" }, "shipments": { "items": { "$ref": "#/components/schemas/PublicTrackingShipment" }, "type": "array", "title": "Shipments" }, "items": { "items": { "$ref": "#/components/schemas/PublicTrackingItem" }, "type": "array", "title": "Items" } }, "type": "object", "required": [ "order_id", "current_status", "destination", "shipments", "items" ], "title": "PublicTrackingResponse", "description": "Public, unauthenticated tracking view for an order.\n\nKeyed by the order's random UUID (used as an unguessable share token). Shows\nthe status, destination, per-package carrier checkpoints, and the ordered\nitems \u2014 everything except the recipient's name and phone." }, "PublicTrackingShipment": { "properties": { "carrier": { "type": "string", "title": "Carrier" }, "tracking_number": { "type": "string", "title": "Tracking Number" }, "status": { "anyOf": [ { "$ref": "#/components/schemas/TrackingStatus" }, { "type": "null" } ] }, "estimated_delivery_date": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Estimated Delivery Date" }, "checkpoints": { "items": { "$ref": "#/components/schemas/TrackingCheckpointResponse" }, "type": "array", "title": "Checkpoints" } }, "type": "object", "required": [ "carrier", "tracking_number" ], "title": "PublicTrackingShipment", "description": "One package (tracking number) on the public tracking page.\n\nIntentionally minimal: carrier + tracking number (the page links to the\ncarrier's own tracking site), status, ETA, and the scan history. The\n17track URL and Zinc alias are deliberately NOT exposed here." }, "RecentCall": { "properties": { "endpoint": { "type": "string", "title": "Endpoint" }, "at": { "type": "string", "title": "At" }, "query": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Query" }, "result_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Result Count" }, "retailer": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Retailer" }, "product_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Product Id" } }, "type": "object", "required": [ "endpoint", "at" ], "title": "RecentCall", "description": "A single metered data-API call, for the \"recent activity\" table." }, "RetailerCheckCheckout": { "properties": { "guest_checkout": { "type": "boolean", "title": "Guest Checkout", "description": "Zinc can check out without a customer account \u2014 the store allows guests, or Zinc holds a shared account for it. When false, an order here must carry `retailer_credentials_id`." }, "use_your_account": { "type": "boolean", "title": "Use Your Account", "description": "The customer can supply their own retailer login." } }, "type": "object", "required": [ "guest_checkout", "use_your_account" ], "title": "RetailerCheckCheckout", "description": "How a customer can pay at this store." }, "RetailerCheckEvidence": { "properties": { "orders_placed": { "type": "boolean", "title": "Orders Placed" }, "last_order_at": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Last Order At" } }, "type": "object", "required": [ "orders_placed" ], "title": "RetailerCheckEvidence", "description": "What Zinc has actually done at this store.\n\nDeliberately coarse \u2014 a boolean and a date. Success *rates* are a\ncompetitive signal." }, "RetailerCheckResponse": { "properties": { "url": { "type": "string", "title": "Url" }, "domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Domain", "description": "Canonical registrable domain, or null if the URL has none." }, "orderable": { "type": "boolean", "title": "Orderable", "description": "Zinc will attempt an order here, given whatever the store requires. True for every support tier except `unsupported` \u2014 including `untested`, a store Zinc has never seen. It is a fact about the store, not about one request: where `checkout.guest_checkout` is false the store still needs a linked account, so pass `retailer_credentials_id` to POST /orders or it will refuse. Check both fields to predict a credential-less order." }, "support": { "type": "string", "title": "Support", "description": "verified: curated, daily test order passing. active: real orders succeeded in the last 90 days. observed: Zinc has attempted orders here. untested: never seen, and Zinc will still try. unsupported: Zinc refuses; see `unsupported_reason`." }, "retailer": { "anyOf": [ { "$ref": "#/components/schemas/RetailerCheckRetailer" }, { "type": "null" } ], "description": "Null when Zinc has no catalog row for the domain." }, "platform": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Platform", "description": "Detected storefront platform, e.g. 'shopify'." }, "checkout": { "anyOf": [ { "$ref": "#/components/schemas/RetailerCheckCheckout" }, { "type": "null" } ] }, "ships_to": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Ships To", "description": "Declared destination countries. Null means no claim either way \u2014 the order path enforces nothing, so do not read it as 'US only'." }, "evidence": { "anyOf": [ { "$ref": "#/components/schemas/RetailerCheckEvidence" }, { "type": "null" } ] }, "support_detail": { "type": "string", "title": "Support Detail", "description": "What `support` means for this store, in prose, and whether to go ahead. Every orderable tier says so explicitly \u2014 `untested` in particular means 'never seen it, try anyway', which the tier name alone does not convey." }, "unsupported_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Unsupported Reason", "description": "Error code Zinc would refuse with, matching POST /orders." }, "how_to_order": { "type": "string", "title": "How To Order", "description": "What to do next. Carries the ordering instruction when `orderable` is true, and tells you not to submit when it is false." } }, "type": "object", "required": [ "url", "orderable", "support", "support_detail", "how_to_order" ], "title": "RetailerCheckResponse", "description": "Can Zinc buy from this store, and ship it where the caller wants?" }, "RetailerCheckRetailer": { "properties": { "retailer": { "type": "string", "title": "Retailer", "description": "Storefront slug, e.g. 'amazon-de'" }, "brand": { "type": "string", "title": "Brand", "description": "Brand slug, e.g. 'amazon'" }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Display Name" }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Country", "description": "The market this storefront is, or null when unscoped." } }, "type": "object", "required": [ "retailer", "brand" ], "title": "RetailerCheckRetailer", "description": "The storefront a checked URL resolves to, when we have one." }, "RetailerCredentialsCreate": { "properties": { "email": { "type": "string", "title": "Email" }, "password": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Password" }, "retailer": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Retailer", "description": "Retailer name (e.g., 'amazon'). If null, applies as default credentials." }, "totp_secret": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Totp Secret", "description": "TOTP secret key for 2FA (will be encrypted at rest)." }, "retailer_config": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Retailer Config" } }, "type": "object", "required": [ "email" ], "title": "RetailerCredentialsCreate", "description": "Request model for creating retailer credentials." }, "RetailerCredentialsListResponse": { "properties": { "credentials": { "items": { "$ref": "#/components/schemas/RetailerCredentialsResponse" }, "type": "array", "title": "Credentials" }, "total": { "type": "integer", "title": "Total" } }, "type": "object", "required": [ "credentials", "total" ], "title": "RetailerCredentialsListResponse", "description": "Response model for list of retailer credentials." }, "RetailerCredentialsResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "short_id": { "type": "string", "title": "Short Id" }, "email": { "type": "string", "title": "Email" }, "retailer": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Retailer" }, "retailer_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Retailer Id", "description": "The storefront this credential logs in to. NULL when its `retailer` slug has no catalog row \u2014 the two are kept in step automatically, so a NULL here means the slug is not (yet) a known storefront." }, "has_totp": { "type": "boolean", "title": "Has Totp", "description": "Whether TOTP 2FA is configured for this account.", "default": false }, "has_forwarding": { "type": "boolean", "title": "Has Forwarding", "description": "Whether email forwarding has been verified for this account.", "default": false }, "is_paused": { "type": "boolean", "title": "Is Paused", "description": "Whether this credential is paused (jobs will not be picked up).", "default": false }, "locked_by_job_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Locked By Job Id", "description": "The job ID currently using this credential, if any." }, "cooldown_minutes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Cooldown Minutes", "description": "Minimum minutes between uses. None = no cooldown." }, "last_used_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Used At", "description": "When this credential was last released after a job completed." }, "retailer_config": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Retailer Config" }, "forwarding_email": { "type": "string", "title": "Forwarding Email", "description": "Email address to forward retailer emails to for verification and 2FA code extraction." }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At" } }, "type": "object", "required": [ "id", "short_id", "email", "retailer", "forwarding_email", "created_at", "updated_at" ], "title": "RetailerCredentialsResponse", "description": "Response model for retailer credentials." }, "RetailerCredentialsUpdate": { "properties": { "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email" }, "password": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Password" }, "retailer": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Retailer" }, "totp_secret": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Totp Secret" }, "retailer_config": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Retailer Config" } }, "type": "object", "title": "RetailerCredentialsUpdate", "description": "Request model for updating retailer credentials." }, "ReturnRequestCreate": { "properties": { "order_id": { "type": "string", "format": "uuid", "title": "Order Id" }, "items": { "items": { "$ref": "#/components/schemas/ReturnRequestItem" }, "type": "array", "minItems": 1, "title": "Items", "description": "Per-product lines being returned" }, "reason": { "$ref": "#/components/schemas/ReturnRequestReason" }, "notes": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ], "title": "Notes" } }, "type": "object", "required": [ "order_id", "items", "reason" ], "title": "ReturnRequestCreate" }, "ReturnRequestItem": { "properties": { "order_item_id": { "type": "string", "format": "uuid", "title": "Order Item Id" }, "quantity": { "type": "integer", "maximum": 100.0, "minimum": 1.0, "title": "Quantity" } }, "type": "object", "required": [ "order_item_id", "quantity" ], "title": "ReturnRequestItem", "description": "A single product line on a return \u2014 which order item, how many." }, "ReturnRequestListResponse": { "properties": { "return_requests": { "items": { "$ref": "#/components/schemas/ReturnRequestResponse" }, "type": "array", "title": "Return Requests" }, "total": { "type": "integer", "title": "Total" } }, "type": "object", "required": [ "return_requests", "total" ], "title": "ReturnRequestListResponse" }, "ReturnRequestReason": { "type": "string", "enum": [ "damaged", "not_delivered", "empty_box", "wrong_item", "defective", "not_as_described", "wrong_size", "no_longer_needed", "forced_cancellation", "other" ], "title": "ReturnRequestReason", "description": "Universal return reason codes (Shopify + Amazon prepaid alignment)." }, "ReturnRequestResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "order_id": { "type": "string", "format": "uuid", "title": "Order Id" }, "status": { "$ref": "#/components/schemas/ReturnRequestStatus" }, "reason": { "$ref": "#/components/schemas/ReturnRequestReason" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Notes" }, "resolution_notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Resolution Notes" }, "items": { "items": { "$ref": "#/components/schemas/ReturnRequestItem" }, "type": "array", "title": "Items", "default": [] }, "label_urls": { "items": { "type": "string" }, "type": "array", "title": "Label Urls", "default": [] }, "merchant_return_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Merchant Return Id" }, "credited_amount": { "type": "integer", "title": "Credited Amount", "description": "Total wallet credit issued for this return, in cents. 0 until a credit is issued (and on returns resolved without one). Credits are append-only, so this is the running total across every credit and reversal on the return, not the last one.", "default": 0 }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At" } }, "type": "object", "required": [ "id", "order_id", "status", "reason", "notes", "created_at", "updated_at" ], "title": "ReturnRequestResponse" }, "ReturnRequestStatus": { "type": "string", "enum": [ "open", "approved", "denied", "credited" ], "title": "ReturnRequestStatus" }, "ReturnRequestSummary": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "status": { "$ref": "#/components/schemas/ReturnRequestStatus" }, "reason": { "$ref": "#/components/schemas/ReturnRequestReason" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Notes" }, "resolution_notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Resolution Notes" }, "items": { "items": { "$ref": "#/components/schemas/ReturnRequestItem" }, "type": "array", "title": "Items", "default": [] }, "label_urls": { "items": { "type": "string" }, "type": "array", "title": "Label Urls", "default": [] }, "credited_amount": { "type": "integer", "title": "Credited Amount", "description": "Total wallet credit issued for this return, in cents. 0 until a credit is issued (and on returns resolved without one). Credits are append-only, so this is the running total across every credit and reversal on the return, not the last one.", "default": 0 }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At" } }, "type": "object", "required": [ "id", "status", "reason", "created_at", "updated_at" ], "title": "ReturnRequestSummary" }, "SandboxClaimRequest": { "properties": { "token": { "type": "string", "maxLength": 128, "minLength": 1, "title": "Token" } }, "type": "object", "required": [ "token" ], "title": "SandboxClaimRequest", "description": "The raw claim token from a claim URL." }, "SandboxClaimResponse": { "properties": { "claimed": { "type": "boolean", "title": "Claimed" }, "orders_moved": { "type": "integer", "title": "Orders Moved" }, "keys_moved": { "type": "integer", "title": "Keys Moved" }, "message": { "type": "string", "title": "Message" } }, "type": "object", "required": [ "claimed", "orders_moved", "keys_moved", "message" ], "title": "SandboxClaimResponse", "description": "What a completed claim moved onto the account." }, "SandboxClaimSummary": { "properties": { "orders_moved": { "type": "integer", "title": "Orders Moved" }, "keys_moved": { "type": "integer", "title": "Keys Moved" }, "note": { "type": "string", "title": "Note", "default": "Your sandbox order history and its key now belong to this account. The sandbox key keeps working for test mode; use the live key for real orders." } }, "type": "object", "required": [ "orders_moved", "keys_moved" ], "title": "SandboxClaimSummary", "description": "What claiming the agent's sandbox moved onto the approving account." }, "SandboxKeyCreate": { "properties": { "email": { "anyOf": [ { "type": "string", "maxLength": 254 }, { "type": "null" } ], "title": "Email", "description": "(optional) Your operator's email address \u2014 we'll send them a link to claim this sandbox and its order history when they want a live account. Never used for anything else, and never required." }, "name": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "title": "Name", "description": "(optional) What this key is for, e.g. 'acme-shopping-agent dev testing'. Becomes the key's label." } }, "type": "object", "title": "SandboxKeyCreate", "description": "Optional context for a sandbox key mint.\n\nAn empty body (or none at all) is valid \u2014 nothing here gates the mint." }, "SandboxKeyResponse": { "properties": { "api_key": { "type": "string", "title": "Api Key", "description": "Sandbox API key (zn_test_...). Send as `Authorization: Bearer