{ "openapi": "3.1.0", "info": { "title": "Zinc", "summary": "Zinc lets you search, buy, and return items from top online retailers with a single API.", "description": "Search, buy, and return items from top online retailers with a single API. Supports AI agent ordering via MPP (HTTP 402) — no account required.", "version": "2026-06-11", "x-logo": { "url": "https://mintlify.s3.us-west-1.amazonaws.com/zinc/logo/light.png" }, "x-guidance": "Zinc lets AI agents buy products from online retailers via a single API. Use POST /agent/orders to place an order — no Zinc account needed, payment is handled via MPP (HTTP 402 flow). Provide a product URL (e.g. Amazon), shipping address, and max_price in cents. The API charges max_price + $1 API fee upfront and refunds the difference on completion. Authenticated endpoints (orders, products, managed-accounts) require a Bearer token (API key prefixed zn_). Docs: https://zinc.com/docs" }, "paths": { "/orders/bulk/validate": { "post": { "tags": [ "orders" ], "summary": "Validate Bulk Upload", "description": "Dry-run a CSV upload: validate every row and report estimated spend.\n\nNo orders are placed. Use this to show the confirmation preview before\ncalling POST /orders/bulk.", "operationId": "validate_bulk_upload_orders_bulk_validate_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/BulkUploadRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkValidateResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/orders/bulk": { "post": { "tags": [ "orders" ], "summary": "Create Bulk Upload", "description": "Create a bulk-upload batch and place its rows asynchronously.", "operationId": "create_bulk_upload_orders_bulk_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/BulkUploadRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkBatchResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "orders" ], "summary": "List Bulk Uploads", "description": "List the current user's bulk-upload batches, newest first.", "operationId": "list_bulk_uploads_orders_bulk_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } }, { "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/BulkBatchListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/orders/bulk/{batch_id}": { "get": { "tags": [ "orders" ], "summary": "Get Bulk Upload", "description": "Get a batch with per-row results and live order statuses.", "operationId": "get_bulk_upload_orders_bulk__batch_id__get", "parameters": [ { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Batch 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/BulkBatchResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/orders/bulk/{batch_id}/results.csv": { "get": { "tags": [ "orders" ], "summary": "Download Bulk Results", "description": "Download the batch results as a CSV (status + echoed custom columns).", "operationId": "download_bulk_results_orders_bulk__batch_id__results_csv_get", "parameters": [ { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Batch Id" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/orders": { "post": { "tags": [ "orders" ], "summary": "Create Order", "description": "Posts an order to a queue for processing", "operationId": "create_order_orders_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/OrderCreate" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "orders" ], "summary": "List Orders", "description": "Get a list of orders for the current user", "operationId": "list_orders_orders_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "description": "Number of orders to return", "default": 50, "title": "Limit" }, "description": "Number of orders to return" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Number of orders to skip", "default": 0, "title": "Offset" }, "description": "Number of orders to skip" }, { "name": "order_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by order ID (partial match)", "title": "Order Id" }, "description": "Filter by order ID (partial match)" }, { "name": "status_filter", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by order status", "title": "Status Filter" }, "description": "Filter by order status" }, { "name": "return_status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by return-request status. `open` → orders with at least one open return. `closed` → orders with at least one approved or denied return. Omit for no filter.", "title": "Return Status" }, "description": "Filter by return-request status. `open` → orders with at least one open return. `closed` → orders with at least one approved or denied return. Omit for no filter." }, { "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/OrderListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/orders/test-products": { "get": { "tags": [ "orders" ], "summary": "List Test Products", "description": "Get list of test products for sandbox testing.\n\nReturns list of test product URLs that can be used with test API keys\nto trigger different test scenarios.", "operationId": "list_test_products_orders_test_products_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response List Test Products Orders Test Products Get" } } } } } } }, "/orders/{order_id}": { "get": { "tags": [ "orders" ], "summary": "Get Order", "description": "Retrieves an order by its ID", "operationId": "get_order_orders__order_id__get", "parameters": [ { "name": "order_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Order 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/OrderResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/orders/{order_id}/events": { "get": { "tags": [ "orders" ], "summary": "Get Order Events", "description": "Get progress events for an order.\n\nReturns the progress events from the latest non-debug job for the order.\nUsers can only see events for their own orders.", "operationId": "get_order_events_orders__order_id__events_get", "parameters": [ { "name": "order_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Order 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/OrderEventsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/orders/{order_id}/cancel": { "post": { "tags": [ "orders" ], "summary": "Cancel Order", "description": "Cancel an order by its ID. Orders can only be cancelled if they are pending.", "operationId": "cancel_order_orders__order_id__cancel_post", "parameters": [ { "name": "order_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Order 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" } } } } } } }, "/products/search": { "get": { "tags": [ "products" ], "summary": "Search Products", "description": "Search for products on a retailer.", "operationId": "search_products_products_search_get", "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": { "enum": [ "amazon", "walmart" ], "type": "string", "description": "Retailer identifier", "title": "Retailer" }, "description": "Retailer identifier" }, { "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": "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/ProductSearchResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/products/{product_id}/offers": { "get": { "tags": [ "products" ], "summary": "Get Product Offers", "description": "Get offers for a product from a retailer.", "operationId": "get_product_offers_products__product_id__offers_get", "parameters": [ { "name": "product_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Product Id" } }, { "name": "retailer", "in": "query", "required": true, "schema": { "enum": [ "amazon", "walmart" ], "type": "string", "description": "Retailer identifier", "title": "Retailer" }, "description": "Retailer identifier" }, { "name": "max_age", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Max response age in seconds (mutually exclusive with newer_than)", "title": "Max Age" }, "description": "Max response age in seconds (mutually exclusive with newer_than)" }, { "name": "newer_than", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Minimum retrieval timestamp (mutually exclusive with max_age)", "title": "Newer Than" }, "description": "Minimum retrieval timestamp (mutually exclusive with max_age)" }, { "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" }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "title": "Response Get Product Offers Products Product Id Offers Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/products/{product_id}": { "get": { "tags": [ "products" ], "summary": "Get Product Details", "description": "Get details for a product from a retailer.", "operationId": "get_product_details_products__product_id__get", "parameters": [ { "name": "product_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Product Id" } }, { "name": "retailer", "in": "query", "required": true, "schema": { "enum": [ "amazon", "walmart" ], "type": "string", "description": "Retailer identifier", "title": "Retailer" }, "description": "Retailer identifier" }, { "name": "max_age", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Max response age in seconds (mutually exclusive with newer_than)", "title": "Max Age" }, "description": "Max response age in seconds (mutually exclusive with newer_than)" }, { "name": "newer_than", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Minimum retrieval timestamp (mutually exclusive with max_age)", "title": "Newer Than" }, "description": "Minimum retrieval timestamp (mutually exclusive with max_age)" }, { "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" }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "title": "Response Get Product Details Products Product Id Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/search": { "get": { "tags": [ "search" ], "summary": "Search", "description": "Search for products across retailers; returns orderable zn_sku_ listings.", "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": "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" } } } } } } }, "/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": "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.\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": "Create Mpp Order", "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.", "operationId": "create_mpp_order_agent_orders_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/OrderCreate" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderResponse" } } }, "headers": { "X-Api-Key": { "description": "API key for the MPP agent to check order status via GET /orders/{id}", "schema": { "type": "string" } }, "Payment-Receipt": { "description": "MPP payment receipt confirming the charge", "schema": { "type": "string" } } } }, "402": { "description": "Payment required — returns challenge details for each configured payment method", "headers": { "WWW-Authenticate": { "description": "One header per supported payment method with challenge parameters (per RFC 9110 §11.6.1)", "schema": { "type": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-payment-info": { "pricingMode": "quote", "protocols": [ "mpp" ], "authMode": "paid" }, "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" } } } }, "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": "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" } } } } } } }, "/health": { "get": { "tags": [ "health" ], "summary": "Get Public Health", "description": "Customer-facing platform health.\n\nNo auth. Cached in-process for 4 minutes — 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", "title": "Address Line1" }, "address_line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Address Line2" }, "city": { "type": "string", "title": "City" }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "State" }, "postal_code": { "type": "string", "title": "Postal Code" }, "phone_number": { "type": "string", "title": "Phone Number" }, "country": { "type": "string", "title": "Country", "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\")." }, "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" }, "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." } }, "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" }, "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." }, "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" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "JobResultPayload": { "properties": { "job_id": { "type": "string", "title": "Job Id" }, "status": { "type": "string", "title": "Status" }, "success": { "type": "boolean", "title": "Success", "default": false }, "duration_seconds": { "type": "number", "title": "Duration Seconds", "default": 0 }, "session_ip": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Session Ip" }, "extracted_data": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Extracted Data" }, "price_components": { "anyOf": [ { "$ref": "#/components/schemas/PriceComponents" }, { "type": "null" } ] }, "merchant_order_ids": { "anyOf": [ { "items": { "$ref": "#/components/schemas/MerchantOrderId" }, "type": "array" }, { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Merchant Order Ids" }, "estimated_delivery": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Estimated Delivery" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "error_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error Type" }, "total_input_tokens": { "type": "integer", "title": "Total Input Tokens" }, "total_output_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Output Tokens" }, "total_cache_read_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Cache Read Tokens" }, "total_cache_write_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Cache Write Tokens" }, "screenshot_urls": { "items": { "type": "string" }, "type": "array", "title": "Screenshot Urls", "default": [] }, "log_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Log Url" } }, "additionalProperties": true, "type": "object", "required": [ "job_id", "status", "total_input_tokens" ], "title": "JobResultPayload", "description": "Job result payload received from sonic" }, "LineItem": { "properties": { "description": { "type": "string", "title": "Description" }, "amount": { "type": "integer", "title": "Amount" }, "category": { "type": "string", "title": "Category" } }, "type": "object", "required": [ "description", "amount", "category" ], "title": "LineItem" }, "MerchantOrderId": { "properties": { "merchant_order_id": { "type": "string", "title": "Merchant Order Id" }, "merchant": { "type": "string", "title": "Merchant", "default": "zinc" }, "placed_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Placed At" } }, "additionalProperties": true, "type": "object", "required": [ "merchant_order_id" ], "title": "MerchantOrderId" }, "OrderCreate": { "properties": { "products": { "items": { "$ref": "#/components/schemas/OrderProduct" }, "type": "array", "title": "Products" }, "shipping_address": { "$ref": "#/components/schemas/Address" }, "max_price": { "type": "integer", "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 specific retailer credentials to use for this order. If not provided, credentials will be selected automatically." }, "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." } }, "type": "object", "required": [ "products", "shipping_address", "max_price" ], "title": "OrderCreate", "description": "Request model for creating a new order." }, "OrderEventsResponse": { "properties": { "events": { "items": { "$ref": "#/components/schemas/ProgressEventResponse" }, "type": "array", "title": "Events" }, "job_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Job Id" } }, "type": "object", "required": [ "events", "job_id" ], "title": "OrderEventsResponse", "description": "Response model for order progress events." }, "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" }, "status": { "$ref": "#/components/schemas/OrderItemStatus" }, "cancellation_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cancellation Reason" }, "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." }, "OrderItemStatus": { "type": "string", "enum": [ "pending", "processing", "ordered", "shipped", "delivered", "cancelled", "failed" ], "title": "OrderItemStatus" }, "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" }, "OrderProduct": { "properties": { "url": { "type": "string", "title": "Url", "examples": [ "https://www.amazon.com/dp/B07JGBW826" ] }, "quantity": { "type": "integer", "maximum": 100, "minimum": 1, "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)" } }, "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" }, "retailer_credentials_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Retailer Credentials Id" }, "retailer_credentials_uuid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Retailer Credentials Uuid" }, "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": [] }, "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" }, "PriceComponents": { "properties": { "subtotal": { "type": "integer", "title": "Subtotal" }, "tax": { "type": "integer", "title": "Tax" }, "shipping": { "type": "integer", "title": "Shipping" }, "total": { "type": "integer", "title": "Total" }, "converted_payment_total": { "type": "integer", "title": "Converted Payment Total" }, "currency": { "type": "string", "title": "Currency" }, "payment_currency": { "type": "string", "title": "Payment Currency" }, "line_items": { "items": { "$ref": "#/components/schemas/LineItem" }, "type": "array", "title": "Line Items", "default": [] } }, "type": "object", "required": [ "subtotal", "tax", "shipping", "total", "converted_payment_total", "currency", "payment_currency" ], "title": "PriceComponents" }, "ProductSearchResponse": { "properties": { "status": { "type": "string", "title": "Status" }, "results": { "items": { "$ref": "#/components/schemas/ProductSearchResult" }, "type": "array", "title": "Results", "default": [] } }, "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" } }, "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.)." }, "ProgressEventResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "job_id": { "type": "string", "format": "uuid", "title": "Job Id" }, "event_name": { "type": "string", "title": "Event Name" }, "elapsed_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Elapsed Seconds" }, "current_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Current Url" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" } }, "type": "object", "required": [ "id", "job_id", "event_name", "elapsed_seconds", "current_url", "created_at" ], "title": "ProgressEventResponse", "description": "Response model for a single progress event." }, "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" }, "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" }, "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, "minimum": 1, "title": "Quantity" } }, "type": "object", "required": [ "order_item_id", "quantity" ], "title": "ReturnRequestItem", "description": "A single product line on a return — which order item, how many." }, "ReturnRequestListResponse": { "properties": { "return_requests": { "items": { "$ref": "#/components/schemas/ReturnRequestResponse" }, "type": "array", "title": "Return Requests" } }, "type": "object", "required": [ "return_requests" ], "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" }, "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": [] }, "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" }, "SearchResponse": { "properties": { "status": { "type": "string", "title": "Status" }, "query": { "type": "string", "title": "Query" }, "results": { "items": { "$ref": "#/components/schemas/Sku" }, "type": "array", "title": "Results", "default": [] } }, "type": "object", "required": [ "status", "query" ], "title": "SearchResponse", "description": "Response from the cross-retailer search endpoint." }, "Sku": { "properties": { "url": { "type": "string", "title": "Url" }, "retailer": { "type": "string", "title": "Retailer" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "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" }, "available": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Available" } }, "type": "object", "required": [ "url", "retailer" ], "title": "Sku", "description": "A cross-retailer buyable listing. Pass `url` to /orders to buy it." }, "TrackingNumberResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "carrier": { "type": "string", "title": "Carrier" }, "tracking_number": { "type": "string", "title": "Tracking Number" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" } }, "type": "object", "required": [ "id", "carrier", "tracking_number", "created_at" ], "title": "TrackingNumberResponse", "description": "Response model for tracking number data." }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } }, "securitySchemes": { "BearerAuth": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Zinc API key (Bearer zn_...)" } } }, "servers": [ { "url": "https://api.zinc.com", "description": "Production" } ], "security": [ { "BearerAuth": [] } ] }