--- updatedAt: 2026-09-04T11:23:25.000Z agentTools: projectIndex: https://docs.us.zip.co/llms.txt --- # /orders/authorize Sandbox (Testing): https://gateway.sand.us.zip.co/orders/authorize Creates a new checkout context and redirects to the checkout website using details from the request body. Sent from the user's browser via a form POST, will start a checkout session within Zip. It will automatically redirect the user to our Zip checkout. You need to ensure you provide your merchant ID, merchant reference (the unique ID you use for the order in your system), confirm/cancel URLs, and the order amount. The order amount should include all shipping, tax, and discount charges. You do not need to provide the order ID as that will be generated for you. Passing as much customer information as possible will improve the user experience by pre-filling data fields and improving conversion. [block:api-header] { "title": "Important Notes" } [/block] **Example — "Success: True" Response** [block:code] { "codes": [ { "code": "{ \n “Amount”: 400, \n “Currency”: “USD”,\n “MerchantId”: “44444444-4444-4444-4444-444444444444”,\n “MerchantReference”: “1234-1”,\n “OrderId”: “0050c1d4-d360-4bc6-9252-de1fb24d379d”, \n \t“Success”: True,\n “Territory”: US,\n \t“Test”: False,\n \t“Timestamp”: “2022-02-25T15:00:43.8391167Z”\n}", "language": "json", "name": "Success: True" } ] } [/block] **Example — "Success: False" Response** * No callback webhook responses are provided when an order limit exceeds the maximum order limit. For example, if your Zip merchant account has a maximum order limit of $1,500, but a request is made for $2,000, there will be an error message displayed in the Zip checkout flow: “There was a problem starting your order. Your requested order amount of $2,000.00 was more than \[merchant]'s supported maximum order amount of $1,500.00." # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "gateway-api-1", "version": "1.0" }, "servers": [ { "url": "https://gateway.us.zip.co" } ], "components": { "securitySchemes": { "sec0": { "type": "oauth2", "flows": { "clientCredentials": { "tokenUrl": "https://example.com/oauth2/token", "scopes": {} } } } } }, "security": [ { "sec0": [] } ], "paths": { "/orders/authorize": { "post": { "summary": "/orders/authorize", "description": "Sandbox (Testing): https://gateway.sand.us.zip.co/orders/authorize\n\nCreates a new checkout context and redirects to the checkout website using details from the request body.\n\nSent from the user's browser via a form POST, will start a checkout session within Zip. It will automatically redirect the user to our Zip checkout. You need to ensure you provide your merchant ID, merchant reference (the unique ID you use for the order in your system), confirm/cancel URLs, and the order amount. The order amount should include all shipping, tax, and discount charges. You do not need to provide the order ID as that will be generated for you. Passing as much customer information as possible will improve the user experience by pre-filling data fields and improving conversion.", "operationId": "ordersauthorize", "parameters": [ { "name": "QP-Territory", "in": "header", "description": "Territory of the request (US)", "required": true, "schema": { "type": "string" } }, { "name": "X-QP-Signature", "in": "header", "description": "The signature for merchant validation", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "merchantId", "merchantReference", "callbackUrl", "redirectCancelUrl", "redirectConfirmUrl" ], "properties": { "orderId": { "type": "string", "description": "Gets or sets the unique ID to use for order creation" }, "merchantId": { "type": "string", "description": "Gets or sets the merchant Id" }, "merchantReference": { "type": "string", "description": "Gets or sets the unique merchant reference for this authorization." }, "order": { "type": "object", "description": "Encapsulates an order to create for a merchant", "required": [ "firstName", "lastName", "email", "phone", "amount" ], "properties": { "firstName": { "type": "string", "description": "Gets or sets the customer's first name." }, "lastName": { "type": "string", "description": "Gets or sets the customer's last name." }, "email": { "type": "string", "description": "Gets or sets the customer's email address." }, "phone": { "type": "string", "description": "Gets or sets the customer's phone number." }, "shippingAddress": { "type": "object", "description": "Encapsulates a physical address.", "properties": { "line1": { "type": "string", "description": "Gets or sets the first address line." }, "line2": { "type": "string", "description": "Gets or sets the second address line." }, "city": { "type": "string", "description": "Gets or sets the city." }, "state": { "type": "string", "description": "Gets or sets the state or province." }, "postalCode": { "type": "string", "description": "Gets or sets the postal code." }, "country": { "type": "string", "description": "Gets or sets the country." } } }, "billingAddress": { "type": "object", "description": "Encapsulates a physical address.", "required": [ "line1", "line2", "city", "state", "postalCode", "country" ], "properties": { "line1": { "type": "string", "description": "Gets or sets the first address line." }, "line2": { "type": "string", "description": "Gets or sets the second address line." }, "city": { "type": "string", "description": "Gets or sets the city." }, "state": { "type": "string", "description": "Gets or sets the state or province." }, "postalCode": { "type": "string", "description": "Gets or sets the postal code." }, "country": { "type": "string", "description": "Gets or sets the country." } } }, "currency": { "type": "string", "description": "Gets or sets the currency the order amount is in (defaults to TerritorySettings)." }, "amount": { "type": "number", "description": "Gets or sets the order amount. This includes the tax and shipping amounts.", "format": "double" }, "taxAmount": { "type": "number", "description": "Gets or sets the optional tax amount.", "format": "double" }, "shippingAmount": { "type": "number", "description": "Gets or sets the optional shipping amount.", "format": "double" }, "lineItems": { "type": "array", "description": "Gets or sets the optional line items of what the user is purchasing.", "items": { "properties": { "description": { "type": "string", "description": "Gets or sets a description about the item being purchased." }, "name": { "type": "string", "description": "Gets or sets the name of the item being purchased." }, "quantity": { "type": "integer", "description": "Gets or sets the quantity of the items being purchased.", "format": "int32" }, "price": { "type": "number", "description": "Gets or sets the price of a single item.", "format": "double" }, "sku": { "type": "string", "description": "Gets or sets the SKU identifier of the item being purchased." }, "isPreOrder": { "type": "boolean", "description": "Gets or sets the flag indicating whether or not this item will be included in a preorder" }, "releaseDate": { "type": "string", "description": "Gets or sets the date a preorder order will be shipped", "format": "date" } }, "type": "object" } }, "description": { "type": "string", "description": "Gets or sets a description for the order." }, "orderNumber": { "type": "string", "description": "Gets or sets the Zip order number." } } }, "test": { "type": "boolean", "description": "Gets or sets a value indicating whether this is a test order" }, "capture": { "type": "boolean", "description": "Gets or sets a value indicating whether this order should be immediately captured" }, "callbackUrl": { "type": "string", "description": "Gets or sets the status callback url" }, "redirectCancelUrl": { "type": "string", "description": "Gets or sets the url that the user will be redirected to if they cancel the checkout" }, "redirectConfirmUrl": { "type": "string", "description": "Gets or sets the url that the user will be redirected to after they have completed the checkout." }, "metadata": { "type": "object", "description": "Gets or sets optional metadata attached to the checkout", "properties": {} }, "checkoutFlow": { "type": "string", "description": "Gets or sets the type of the checkout; defaults to Standard; can only be set internally" }, "brandName": { "type": "string", "description": "Gets or sets the brand name of the merchant for this order" } } } } } }, "responses": { "302": { "description": "302", "content": { "application/json": { "examples": { "Redirect": { "value": "" } } } } } }, "deprecated": false, "security": [], "x-readme": { "code-samples": [ { "language": "text", "code": "curl --request POST \\\n --url https://gateway.us.zip.co/orders/authorize \\\n --header 'Content-Type: application/json' \\\n --header 'QP-Territory: US' \\\n --data '\n{\n \"orderId\": \"3fa85f64-5717-4562-b3fc-2c963f66afa6\",\n \"merchantId\": \"3fa85f64-5717-4562-b3fc-2c963f66afa6\",\n \"merchantReference\": \"string\",\n \"order\": {\n \"firstName\": \"string\",\n \"lastName\": \"string\",\n \"email\": \"string\",\n \"phone\": \"string\",\n \"shippingAddress\": {\n \"line1\": \"string\",\n \"line2\": \"string\",\n \"city\": \"string\",\n \"state\": \"string\",\n \"postalCode\": \"string\",\n \"country\": \"string\"\n },\n \"billingAddress\": {\n \"line1\": \"string\",\n \"line2\": \"string\",\n \"city\": \"string\",\n \"state\": \"string\",\n \"postalCode\": \"string\",\n \"country\": \"string\"\n },\n \"currency\": \"string\",\n \"amount\": 0,\n \"taxAmount\": 0,\n \"shippingAmount\": 0,\n \"lineItems\": [\n {\n \"description\": \"string\",\n \"name\": \"string\",\n \"quantity\": 0,\n \"price\": 0,\n \"sku\": \"string\",\n \"isPreOrder\": true,\n \"releaseDate\": \"2021-12-01T16:11:29.525Z\"\n }\n ],\n \"description\": \"string\",\n \"orderNumber\": \"string\"\n },\n \"capture\": true,\n \"callbackUrl\": \"string\",\n \"redirectCancelUrl\": \"string\",\n \"redirectConfirmUrl\": \"string\",\n \"metadata\": {\n \"additionalProp\": \"string\"\n },\n \"merchantFeeForPaymentPlan\": 0,\n \"checkoutFlow\": \"standard\",\n \"brandName\": \"string\"\n}\n\n\n", "name": "Request Example" } ], "samples-languages": [ "text" ] } } } }, "x-readme": { "headers": [], "explorer-enabled": false, "proxy-enabled": false }, "x-readme-fauxas": true } ```