{"uid":"cap_sZJGCw02dhnD_lw3piHmR","slug":"zinc-e-commerce-order-placement-api-7120e132","name":"Zinc E-commerce Order Placement API","description":"Zinc is infrastructure for developers to search products, place orders, and track shipments through one API. Automate your buying process. Start building now!","url":"https://api.zinc.com/agent/orders?utm_source=zero.xyz","method":"POST","headers":{},"bodySchema":{"type":"object","required":["products","max_price","shipping_address"],"properties":{"is_gift":{"type":"boolean","description":"Mark the order as a gift. Prices are suppressed on the packing slip where the fulfillment method supports it."},"payment":{"type":"string","description":"Optional payment block. Omit for prepaid-wallet billing (default)."},"metadata":{"type":"string","description":"Optional metadata to attach to the order. Can contain arbitrary key-value pairs."},"products":{"type":"array"},"max_price":{"type":"integer","description":"Maximum price (in cents) allowed for an order before it is finalized."},"po_number":{"type":"string","description":"Optional purchase order number for the order."},"idempotency_key":{"type":"string","description":"Optional idempotency key to prevent duplicate orders. If not provided, one will be generated."},"shipping_address":{"type":"object","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\")."},"handling_days_max":{"type":"string","description":"Optional ceiling on a seller's shipping and handling days. Omit or send null for no limit."},"customer_notifications":{"type":"string","description":"Opt in to emailing the end customer order updates (and unlock the public tracking page for this order). Adds a per-order surcharge. Omit for no customer notifications (default)."},"retailer_credentials_id":{"type":"string","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."}}},"responseSchema":{"type":"object","title":"OrderResponse","required":["id","status","max_price","attempts","items","shipping_address","retailer_credentials_id","created_at","updated_at"],"properties":{"id":{"type":"string","title":"Id","format":"uuid"},"items":{"type":"array","items":{"type":"object","title":"OrderItemResponse","required":["id","url","quantity","status","created_at","updated_at"],"properties":{"id":{"type":"string","title":"Id","format":"uuid"},"url":{"type":"string","title":"Url"},"status":{"enum":["pending","processing","ordered","shipped","delivered","cancelled","failed"],"type":"string","title":"OrderItemStatus"},"variant":{"anyOf":[{"type":"array","items":{"type":"object","title":"ProductVariant","required":["label","value"],"properties":{"label":{"type":"string","title":"Label","minLength":1,"description":"Variant label (e.g., 'Color', 'Size')"},"value":{"type":"string","title":"Value","minLength":1,"description":"Variant value (e.g., 'Black', 'Large')"}},"description":"Product variant schema for selecting product options (color, size, etc.)."}},{"type":"null"}],"title":"Variant"},"quantity":{"type":"integer","title":"Quantity"},"created_at":{"type":"string","title":"Created At","format":"date-time"},"updated_at":{"type":"string","title":"Updated At","format":"date-time"},"condition_in":{"anyOf":[{"type":"array","items":{"enum":["New","Refurbished","UsedLikeNew","UsedVeryGood","UsedGood","UsedAcceptable"],"type":"string","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."}},{"type":"null"}],"title":"Condition In"},"condition_not_in":{"anyOf":[{"type":"array","items":{"enum":["New","Refurbished","UsedLikeNew","UsedVeryGood","UsedGood","UsedAcceptable"],"type":"string","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."}},{"type":"null"}],"title":"Condition Not In"},"cancellation_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cancellation Reason"}},"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."},"title":"Items"},"status":{"enum":["pending","in_progress","order_placed","order_failed","cancelled","cancelled_by_retailer"],"type":"string","title":"OrderStatus"},"connect":{"anyOf":[{"type":"object","title":"OrderConnectInfo","required":["state"],"properties":{"state":{"type":"string","title":"State","description":"secured | captured | released | refunded | …"},"zinc_fee":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Zinc Fee"},"simulated":{"type":"boolean","title":"Simulated","default":false},"order_cost":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Order Cost","description":"Actual order cost (goods) captured when the order is placed."},"stripe_fee":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Stripe Fee"},"final_charge":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Final Charge"},"secured_amount":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Secured Amount"},"customer_margin":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Customer Margin"},"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"}},"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."},{"type":"null"}],"description":"Stripe Connect charge details when this order was paid via Connect; null for prepaid-wallet orders."},"is_gift":{"type":"boolean","title":"Is Gift","default":false},"returns":{"type":"array","items":{"type":"object","title":"ReturnRequestSummary","required":["id","status","reason","created_at","updated_at"],"properties":{"id":{"type":"string","title":"Id","format":"uuid"},"items":{"type":"array","items":{"type":"object","title":"ReturnRequestItem","required":["order_item_id","quantity"],"properties":{"quantity":{"type":"integer","title":"Quantity","maximum":100,"minimum":1},"order_item_id":{"type":"string","title":"Order Item Id","format":"uuid"}},"description":"A single product line on a return — which order item, how many."},"title":"Items","default":[]},"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Notes"},"reason":{"enum":["damaged","not_delivered","empty_box","wrong_item","defective","not_as_described","wrong_size","no_longer_needed","forced_cancellation","other"],"type":"string","title":"ReturnRequestReason","description":"Universal return reason codes (Shopify + Amazon prepaid alignment)."},"status":{"enum":["open","approved","denied","credited"],"type":"string","title":"ReturnRequestStatus"},"created_at":{"type":"string","title":"Created At","format":"date-time"},"label_urls":{"type":"array","items":{"type":"string"},"title":"Label Urls","default":[]},"updated_at":{"type":"string","title":"Updated At","format":"date-time"},"resolution_notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resolution Notes"}}},"title":"Returns","default":[]},"user_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"User Id"},"attempts":{"type":"integer","title":"Attempts"},"metadata":{"type":"object","title":"Metadata","default":{},"additionalProperties":true},"max_price":{"type":"integer","title":"Max Price"},"po_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Po Number"},"created_at":{"type":"string","title":"Created At","format":"date-time"},"created_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created By"},"job_result":{"anyOf":[{"type":"object","title":"OrderJobResult","properties":{"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"},"success":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Success"},"error_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Type"},"error_details":{"anyOf":[{"type":"object","title":"ErrorDetails","required":["code","message"],"properties":{"code":{"type":"string","title":"Code"},"message":{"type":"string","title":"Message"},"field_errors":{"type":"array","items":{"type":"object","title":"FieldError","required":["field","code"],"properties":{"code":{"type":"string","title":"Code"},"field":{"type":"string","title":"Field"},"message":{"type":"string","title":"Message","default":""},"expected":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expected"},"received":{"title":"Received"}},"description":"A single field-level validation failure from a worker.\n\nMirrors Sonic's `FieldError` (src/agent/types.py): when a job fails schema\nvalidation the worker reports one of these per offending field, so consumers\ncan show \"state should be 'NY', got 'New York'\" instead of a bare count.","additionalProperties":true},"title":"Field Errors","default":[]},"address_validation_reasons":{"type":"array","items":{"type":"string"},"title":"Address Validation Reasons","default":[]}},"description":"Structured detail for a failed job.\n\nAdditive sibling to the flat `error`/`error_type` keys (kept for\nback-compat). The structured home for enrichment beyond the category +\nmessage — e.g. why a shipping address was rejected — so we don't keep\ngrowing loose top-level keys on the job output.","additionalProperties":true},{"type":"null"}]},"price_components":{"anyOf":[{"type":"object","title":"OrderPriceComponents","properties":{"tax":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Tax"},"fees":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Fees","description":"Retailer fees not folded into subtotal/shipping/tax (gift wrap, import/regulatory charges), as a positive magnitude added to the total. Surfaced so a total exceeding the shown parts reads as an itemized fee rather than an unexplained charge."},"total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total","description":"Order total in `currency` (subtotal + tax + shipping + fees − discount)."},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency"},"discount":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Discount","description":"Promotion/free-shipping discount applied by the retailer, as a positive magnitude subtracted from the total. A nonzero `shipping` paired with an equal `discount` means shipping was itemized but waived — the total correctly excludes it."},"shipping":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Shipping"},"subtotal":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Subtotal"},"line_items":{"anyOf":[{"type":"array","items":{"type":"object","additionalProperties":true}},{"type":"null"}],"title":"Line Items","description":"Itemized rows, each `{description, amount, category}`."},"payment_currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Payment Currency"},"converted_payment_total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Converted Payment Total","description":"`total` converted to the currency actually charged."}},"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.","additionalProperties":true},{"type":"null"}]},"estimated_delivery":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Estimated Delivery"},"merchant_order_ids":{"anyOf":[{"type":"array","items":{"type":"object","additionalProperties":true}},{"type":"null"}],"title":"Merchant Order Ids"}},"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.","additionalProperties":true},{"type":"null"}],"description":"Fulfillment result and price breakdown for a completed or failed order; null while processing."},"updated_at":{"type":"string","title":"Updated At","format":"date-time"},"shipping_address":{"type":"object","title":"Shipping Address","additionalProperties":true},"tracking_numbers":{"type":"array","items":{"type":"object","title":"TrackingNumberResponse","required":["id","carrier","tracking_number","created_at"],"properties":{"id":{"type":"string","title":"Id","format":"uuid"},"status":{"anyOf":[{"enum":["pending","in_transit","delivered"],"type":"string","title":"TrackingStatus","description":"Carrier-derived shipment state for a TrackingNumber."},{"type":"null"}],"description":"Carrier-derived shipment state (pending, in_transit, delivered)."},"carrier":{"type":"string","title":"Carrier"},"created_at":{"type":"string","title":"Created At","format":"date-time"},"checkpoints":{"type":"array","items":{"type":"object","title":"TrackingCheckpointResponse","required":["checkpoint_time","status","message"],"properties":{"zip":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Zip"},"city":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"City"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State"},"status":{"enum":["pending","in_transit","delivered"],"type":"string","title":"TrackingStatus","description":"Carrier-derived shipment state at this checkpoint."},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country"},"message":{"type":"string","title":"Message","description":"Carrier-provided description of the scan."},"location":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Location","description":"Free-form location string when city/state are absent."},"checkpoint_time":{"type":"string","title":"Checkpoint Time","format":"date-time","description":"When the carrier recorded this scan event."}},"description":"A single carrier-reported scan event for a tracking number."},"title":"Checkpoints","description":"Carrier scan events, most recent first. Empty unless the checkpoint timeline was requested."},"tracking_number":{"type":"string","title":"Tracking Number"},"zinc_tracking_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Zinc Tracking Url","description":"Public tracking URL for the Zinc tracking number (17track.net)."},"zinc_tracking_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Zinc Tracking Number","description":"Zinc-issued tracking number under pseudo-carrier ZNLOGIC (format ZPY…YQ). Carrier-independent alias for this shipment; assigned once and never changes, even if the carrier tracking is corrected."},"estimated_delivery_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Estimated Delivery Date","description":"Carrier-reported delivery estimate for this shipment, as a destination-local calendar date. Refreshed on every carrier poll; null when the carrier hasn't reported one."}},"description":"Response model for tracking number data.\n\n``status`` is the authoritative carrier-derived shipment state and is always\npresent. ``checkpoints`` is the per-scan timeline; it's embedded on the\nsingle-order read (``GET /orders/{id}``) and, on the list endpoint, only\nwhen ``include=tracking_events`` is requested."},"title":"Tracking Numbers","default":[]},"handling_days_max":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Handling Days Max"},"retailer_credentials_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Retailer Credentials Id"},"retailer_credentials_uuid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Retailer Credentials Uuid"}},"description":"Response model for order data."},"example":null,"exampleRequest":null,"tags":["x402"],"displayCostAmount":"0.01","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"probe","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"static","summary":"$0.01/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.01","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.01","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_FMj8hSoUoQEFzpUkJjZ7i","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.01","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Places automated e-commerce orders for specified products up to a maximum price and ships them to a given address","exampleAgentPrompt":"Order me the Anker USB-C charger at https://www.amazon.com/dp/B07Z6CKH4V, don't spend more than $2500 cents total, ship it to 123 Main St, San Francisco, CA 94105, US, and mark it as a gift.","exampleUseCases":[{"title":"Automated dropshipping fulfillment","prompt":"Place an order for the product at https://www.amazon.com/dp/B08N5WRWNW — up to $4999 cents — and ship it to 456 Oak Ave, Austin, TX 78701, US. Use idempotency key 'order-dropship-20240601-001' so we don't accidentally duplicate it."},{"title":"Corporate gift purchasing at scale","prompt":"Buy me 3 units of the item at https://www.amazon.com/dp/B09G9FPHY6, cap the total at $9999 cents, ship to 789 Corporate Blvd, New York, NY 10001, US, and mark the order as a gift so prices are hidden on the packing slip."},{"title":"Price-capped procurement for inventory restocking","prompt":"Automatically purchase the product listed at https://www.amazon.com/dp/B07XJ8C8F5 only if it comes in under $1500 cents, send it to our warehouse at 321 Warehouse Rd, Chicago, IL 60601, US, and attach PO number PO-2024-0891 to the order."}],"resultDescription":"Returns a JSON object with a UUID order ID, overall order status (pending/processing/ordered/shipped/delivered/cancelled/failed), the maximum price cap, attempt count, an array of ordered items each with their own UUID, URL, quantity, status, variant details, and condition; plus the shipping address, retailer credentials ID used, and created/updated timestamps.","failureModes":["Order total exceeds max_price — order is rejected before finalization","Invalid or unrecognized product URL — item cannot be found or purchased","Shipping address validation failure — unsupported country or missing required fields","Out-of-stock product — item unavailable at the requested condition or price","Duplicate order blocked — idempotency key already used for a prior order","Retailer credentials invalid or expired — authentication with retailer fails","Payment failure — prepaid wallet balance insufficient or payment block rejected"],"whenToPreferThis":"Choose this endpoint when you need to programmatically place real product orders on e-commerce platforms (like Amazon) without manual checkout — especially for dropshipping, procurement automation, or agent-driven purchasing workflows that require idempotency, price caps, and condition filtering. Prefer Zinc over scraping or browser automation when you need a reliable, structured API response with order tracking status included.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-10-22T00:33:16.001Z","isFirstParty":false,"canonicalSlug":"zinc-e-commerce-order-placement-api-7120e132"}