{ "openapi": "3.1.0", "info": { "title": "Zinc ", "summary": "Zinc lets you search, buy, and return items from top online retailers with a single API.", "version": "2026-01-21", "x-logo": { "url": "https://mintlify.s3.us-west-1.amazonaws.com/zinc/logo/light.png" } }, "servers": [ { "url": "https://api.zinc.com", "description": "Production API" } ], "paths": { "/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": "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": "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}/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" } } } } } } } }, "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": { "type": "string", "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", "state", "postal_code", "phone_number" ], "title": "Address", "description": "Shipping address model." }, "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": {}, "type": "array" }, { "type": "null" } ], "title": "Merchant Order Ids" }, "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" }, "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." } }, "type": "object", "required": [ "products", "shipping_address", "max_price" ], "title": "OrderCreate", "description": "Request model for creating a new order." }, "OrderItemResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "url": { "type": "string", "title": "Url" }, "quantity": { "type": "integer", "title": "Quantity" }, "variant": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ProductVariant" }, "type": "array" }, { "type": "null" } ], "title": "Variant" }, "status": { "$ref": "#/components/schemas/OrderItemStatus" }, "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" } }, "type": "object", "required": [ "orders" ], "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": {} }, "retailer_credentials_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Retailer Credentials Id" }, "tracking_numbers": { "items": { "$ref": "#/components/schemas/TrackingNumberResponse" }, "type": "array", "title": "Tracking Numbers", "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" ], "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" } }, "type": "object", "required": [ "subtotal", "tax", "shipping", "total", "converted_payment_total", "currency", "payment_currency" ], "title": "PriceComponents" }, "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.)." }, "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" } } } }