{ "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-19", "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" }, "MarginSpec": { "properties": { "type": { "type": "string", "enum": [ "flat", "percent" ], "title": "Type" }, "value": { "type": "number", "minimum": 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)." }, "OrderConnectInfo": { "properties": { "state": { "type": "string", "title": "State", "description": "secured | captured | released | refunded | …" }, "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`` → ``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." }, "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." }, "handling_days_max": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "title": "Handling Days Max", "description": "Optional ceiling on a seller's handling days. Passed through to the fulfillment worker as the top-level max_shipping_days constraint. Omit or send null for no limit." }, "is_gift": { "type": "boolean", "title": "Is Gift", "description": "Mark the order as a gift. Prices are suppressed on the packing slip where the fulfillment method supports it.", "default": false }, "payment": { "anyOf": [ { "$ref": "#/components/schemas/OrderPayment" }, { "type": "null" } ], "description": "Optional payment block. Omit for prepaid-wallet billing (default)." } }, "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" }, "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" }, "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", "delivered", "cancelled", "failed" ], "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" }, "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 —\nsuccess, price breakdown, errors, merchant order ids, delivery estimate —\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" }, "OrderPayment": { "properties": { "mode": { "type": "string", "enum": [ "wallet", "connect" ], "title": "Mode", "default": "wallet" }, "payment_method": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Payment Method", "description": "Connect mode: the end-customer's vaulted Stripe payment-method id on the customer's connected account." }, "customer": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Customer", "description": "Connect mode: the end-customer's Stripe Customer id (cus_…) 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' ⇒ unchanged prepaid-wallet\nbehavior. mode='connect' charges the end-customer's vaulted card in real time\nvia Stripe Connect (see ConnectService)." }, "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" }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total", "description": "Order total in `currency` (subtotal + tax + shipping)." }, "converted_payment_total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Converted Payment Total", "description": "`total` converted to the currency actually charged." }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Currency" }, "payment_currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Payment Currency" }, "line_items": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Line Items", "description": "Itemized rows, each `{description, amount, category}`." } }, "additionalProperties": true, "type": "object", "title": "OrderPriceComponents", "description": "Retailer price breakdown for an order, all amounts in cents.\n\nLenient by design — every field is optional and unknown keys are preserved\n(``extra=\"allow\"``) — 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, "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)" }, "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 }, "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." }, "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." }, "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" }, "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. The Sonic worker's\nCANONICAL_CONDITIONS (``src/agent/schemas.py``) must use the same strings,\nsince they ride through the job payload unchanged.\n\nThe member *name* is the corresponding Amazon BizAPI offer condition code\n(see ``CONDITION_MAP`` in ``bizapi_service``), so the canonical→BizAPI\nmapping is derived from the enum rather than maintained as a separate table." }, "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": [] } ] }