---
updatedAt: 2026-09-04T11:23:50.000Z
agentTools:
  projectIndex: https://docs.us.zip.co/llms.txt
---

# Create a checkout

The first API call you will make in processing a Zip payment is a call to our /checkouts endpoint. This request is made once a customer chooses to use Zip as their payment method at checkout and will contain all order and customer information. The Zip API will then provide a response that includes a redirect url, allowing you to point the customer to the Zip checkout flow where they will complete their application or log in to their Zip account to confirm the payment.

## /checkouts

**Example Request**

```json
{
    "shopper": {
        "title": "Mr",
        "first_name": "Test",
        "last_name": "Tester",
        "email": "firstname.lastname+{{$timestamp}}@domain.com",
        "phone": "4154154455",
        "billing_address": {
            "first_name": "Test",
            "last_name": "Tester",
            "line1": "10 Spring St",
            "city": "New York City",
            "state": "New York",
            "postal_code": "10001",
            "country": "US"
        }
    },
   "order": {
        "reference": "ref_12345",
        "amount": 200,
        "currency": "USD",
        "items": [
            {
                "name": "Awesome shoes",
                "amount": 60,
                "quantity": 1,
                "type": "sku",
                "reference": "001",
                "image_uri": "https://yourimage.com/shoes_image_url",
                "item_uri": "https://youritem.com/shoes_item_url"
            },
            {
                "name": "Awesome pants",
                "amount": 50,
                "quantity": 1,
                "type": "sku",
                "reference": "002",
                "image_uri": "https://yourimage.com/pants_image_url",
                "item_uri": "https://youritem.com/pants_item_url"
            }
        ],
        "shipping": {
            "pickup": false
        }
    },
    "config": {
        "redirect_uri": "https://localhost/zip_order_complete"
    }
}
```

## Important Notes

The checkout status is given by the **state** parameter in the response. The following are checkout status options:

* created
* approved
* completed
* expired

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "single-merchant-interface-smi-api",
    "version": "1.0"
  },
  "servers": [
    {
      "url": "https://global-api.prod.au.edge.zip.co/merchant"
    }
  ],
  "security": [
    {}
  ],
  "paths": {
    "/checkouts": {
      "post": {
        "summary": "Create a checkout",
        "description": "The first API call you will make in processing a Zip payment is a call to our /checkouts endpoint. This request is made once a customer chooses to use Zip as their payment method at checkout and will contain all order and customer information. The Zip API will then provide a response that includes a redirect url, allowing you to point the customer to the Zip checkout flow where they will complete their application or log in to their Zip account to confirm the payment.",
        "operationId": "checkouts",
        "parameters": [
          {
            "name": "Authorization",
            "in": "header",
            "description": "Bearer {{API Key}}",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Zip-Version",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date",
              "default": "2021-08-25"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "shopper",
                  "order",
                  "config"
                ],
                "properties": {
                  "shopper": {
                    "type": "object",
                    "description": "Customer information object",
                    "properties": {
                      "shopper.title": {
                        "type": "string",
                        "description": "Title of shopper (Mr, Mrs, etc). Must be characters of alphabet only."
                      },
                      "shopper.first_name": {
                        "type": "string",
                        "description": "First name of shopper. Required for BHD, SAR, and AED."
                      },
                      "shopper.last_name": {
                        "type": "string",
                        "description": "Last name of shopper."
                      },
                      "shopper.middle_name": {
                        "type": "string",
                        "description": "Middle name of shopper. Must be characters of alphabet only."
                      },
                      "shopper.phone": {
                        "type": "string",
                        "description": "Phone number of shopper. Must only be numerals (no spaces, special characters or alphabet characters)s)."
                      },
                      "shopper.email": {
                        "type": "string",
                        "description": "Email address of shopper. Required for BHD, SAR, and AED"
                      },
                      "shopper.gender": {
                        "type": "string",
                        "description": "The shopper’s gender. Possible values: Male or Female"
                      },
                      "shopper.birthdate": {
                        "type": "string",
                        "description": "Birth date of buyer in format of yyyy-mm-dd.",
                        "format": "date"
                      }
                    }
                  },
                  "order": {
                    "type": "object",
                    "description": "Order details object.",
                    "required": [
                      "order.reference",
                      "order.amount",
                      "order.currency",
                      "order.shipping",
                      "order.items"
                    ],
                    "properties": {
                      "order.reference": {
                        "type": "string",
                        "description": "Unique order reference id. Can also be passed in to /charges call. If left out one will be automatically generated at this point."
                      },
                      "order.amount": {
                        "type": "string",
                        "description": "Total amount of order. This is the amount that is charged to the customer’s zip account."
                      },
                      "order.currency": {
                        "type": "string",
                        "description": "Transaction currency. Accepted values are AUD, NZD, GBP, USD, ZAR, SGD, and MXN."
                      },
                      "order.shipping": {
                        "type": "object",
                        "description": "Shipping object.",
                        "properties": {}
                      },
                      "order.items": {
                        "type": "string",
                        "description": "Order items object. Required for or USD, GBP, NZD,SGD, and MXN."
                      }
                    }
                  },
                  "features": {
                    "type": "object",
                    "description": "Feature object for extra features required on this checkout",
                    "properties": {
                      "features.tokenisation": {
                        "type": "object",
                        "description": "Tokenisation object – required if you are requesting to tokenise the user’s account.",
                        "properties": {}
                      }
                    }
                  },
                  "config": {
                    "type": "object",
                    "properties": {
                      "config.redirect_uri": {
                        "type": "string",
                        "description": "Redirect URI – where the customer is redirected to following placement of order. This will be an intermediate page or endpoint that performs order finalization, including charging or tokenizing account."
                      }
                    }
                  },
                  "metadata": {
                    "type": "object",
                    "description": "Object containing name value pairs of meta data to be returned whenever recalling this checkout object.",
                    "properties": {}
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "200",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n    \"shopper\": {\n        \"title\": \"Mr\",\n        \"first_name\": \"Test\",\n        \"last_name\": \"Tester\",\n        \"email\": \"firstname.lastname+1646067679@domain.com\",\n        \"phone\": \"4154154455\",\n        \"billing_address\": {\n            \"first_name\": \"Test\",\n            \"last_name\": \"Tester\",\n            \"line1\": \"10 Spring St\",\n            \"city\": \"New york\",\n            \"state\": \"New york\",\n            \"postal_code\": \"1000\",\n            \"country\": \"US\"\n        }\n    },\n    \"order\": {\n        \"reference\": \"ref_1646067679\",\n        \"amount\": 200,\n        \"currency\": \"USD\",\n        \"items\": [\n            {\n                \"name\": \"Awesome shoes\",\n                \"amount\": 60,\n                \"quantity\": 1,\n                \"type\": \"sku\",\n                \"reference\": \"001\",\n                \"image_uri\": \"https://yourimage.com/shoes_image_url\",\n                \"item_uri\": \"https://youritem.com/shoes_item_url\"\n            },\n            {\n                \"name\": \"Awesome pants\",\n                \"amount\": 50,\n                \"quantity\": 1,\n                \"type\": \"sku\",\n                \"reference\": \"002\",\n                \"image_uri\": \"https://yourimage.com/pants_image_url\",\n                \"item_uri\": \"https://youritem.com/pants_item_url\"\n            }\n        ],\n        \"shipping\": {\n            \"pickup\": false\n        }\n    },\n    \"config\": {\n        \"redirect_uri\": \"https://localhost/zip_order_complete\"\n    },\n    \"id\": \"us-00d11005-d30f-405d-b8d5-917a8ab78ba0\",\n    \"uri\": \"https://gateway.sand.us.zip.co/orders/authorize?orderId=00d11005-d30f-405d-b8d5-917a8ab78ba0&merchantId=5901c42b-f41f-476b-a2d4-7d4bc383f7db&merchantReference=ref_1646067679&order.orderNumber=220228-254656&order.firstName=Test&order.lastName=Tester&order.email=firstname.lastname%2b1646067679%40domain.com&order.phone=4154154455&order.billingAddress.line1=10+Spring+St&order.billingAddress.city=New+york&order.billingAddress.state=New+york&order.billingAddress.postalCode=1000&order.billingAddress.country=US&order.amount=200&capture=False&callbackUrl=https%3a%2f%2fapi-ut.quadpay.com%2forder%2fcomplete&redirectCancelUrl=https%3a%2f%2fapi-ut.quadpay.com%3a443%2forder%2fcancel%3forderId%3d00d11005-d30f-405d-b8d5-917a8ab78ba0&redirectConfirmUrl=https%3a%2f%2fapi-ut.quadpay.com%2forder%2fcomplete&metadata.confirmUrl=https%3a%2f%2fglobal-api.sand.au.edge.zip.co%3a443%2fmerchant%2fcallback%3fredirect%3dhttps%253A%252F%252Flocalhost%252Fzip_order_complete%26region%3dus%26ppStatus%3dsuccess%26token%3d00d11005-d30f-405d-b8d5-917a8ab78ba0%26OrderStatus%3dApproved&metadata.cancelUrl=https%3a%2f%2fglobal-api.sand.au.edge.zip.co%3a443%2fmerchant%2fcallback%3fredirect%3dhttps%253A%252F%252Flocalhost%252Fzip_order_complete%26region%3dus%26ppStatus%3dcancelled%26token%3d00d11005-d30f-405d-b8d5-917a8ab78ba0%26OrderStatus%3dAbandoned&X-QP-Signature=OO2OzWfV6EU1sRxNH%2bPFoCHEfZNLEq5SUwkvQvehTlU%3d\",\n    \"type\": \"standard\",\n    \"created\": \"2022-02-28T17:01:22.699Z\",\n    \"state\": \"created\"\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "shopper": {
                      "type": "object",
                      "properties": {
                        "title": {
                          "type": "string",
                          "example": "Mr"
                        },
                        "first_name": {
                          "type": "string",
                          "example": "Test"
                        },
                        "last_name": {
                          "type": "string",
                          "example": "Tester"
                        },
                        "email": {
                          "type": "string",
                          "example": "firstname.lastname+1646067679@domain.com"
                        },
                        "phone": {
                          "type": "string",
                          "example": "4154154455"
                        },
                        "billing_address": {
                          "type": "object",
                          "properties": {
                            "first_name": {
                              "type": "string",
                              "example": "Test"
                            },
                            "last_name": {
                              "type": "string",
                              "example": "Tester"
                            },
                            "line1": {
                              "type": "string",
                              "example": "10 Spring St"
                            },
                            "city": {
                              "type": "string",
                              "example": "New york"
                            },
                            "state": {
                              "type": "string",
                              "example": "New york"
                            },
                            "postal_code": {
                              "type": "string",
                              "example": "1000"
                            },
                            "country": {
                              "type": "string",
                              "example": "US"
                            }
                          }
                        }
                      }
                    },
                    "order": {
                      "type": "object",
                      "properties": {
                        "reference": {
                          "type": "string",
                          "example": "ref_1646067679"
                        },
                        "amount": {
                          "type": "integer",
                          "example": 200,
                          "default": 0
                        },
                        "currency": {
                          "type": "string",
                          "example": "USD"
                        },
                        "items": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "name": {
                                "type": "string",
                                "example": "Awesome shoes"
                              },
                              "amount": {
                                "type": "integer",
                                "example": 60,
                                "default": 0
                              },
                              "quantity": {
                                "type": "integer",
                                "example": 1,
                                "default": 0
                              },
                              "type": {
                                "type": "string",
                                "example": "sku"
                              },
                              "reference": {
                                "type": "string",
                                "example": "001"
                              },
                              "image_uri": {
                                "type": "string",
                                "example": "https://yourimage.com/shoes_image_url"
                              },
                              "item_uri": {
                                "type": "string",
                                "example": "https://youritem.com/shoes_item_url"
                              }
                            }
                          }
                        },
                        "shipping": {
                          "type": "object",
                          "properties": {
                            "pickup": {
                              "type": "boolean",
                              "example": false,
                              "default": true
                            }
                          }
                        }
                      }
                    },
                    "config": {
                      "type": "object",
                      "properties": {
                        "redirect_uri": {
                          "type": "string",
                          "example": "https://localhost/zip_order_complete"
                        }
                      }
                    },
                    "id": {
                      "type": "string",
                      "example": "us-00d11005-d30f-405d-b8d5-917a8ab78ba0"
                    },
                    "uri": {
                      "type": "string",
                      "example": "https://gateway.sand.us.zip.co/orders/authorize?orderId=00d11005-d30f-405d-b8d5-917a8ab78ba0&merchantId=5901c42b-f41f-476b-a2d4-7d4bc383f7db&merchantReference=ref_1646067679&order.orderNumber=220228-254656&order.firstName=Test&order.lastName=Tester&order.email=firstname.lastname%2b1646067679%40domain.com&order.phone=4154154455&order.billingAddress.line1=10+Spring+St&order.billingAddress.city=New+york&order.billingAddress.state=New+york&order.billingAddress.postalCode=1000&order.billingAddress.country=US&order.amount=200&capture=False&callbackUrl=https%3a%2f%2fapi-ut.quadpay.com%2forder%2fcomplete&redirectCancelUrl=https%3a%2f%2fapi-ut.quadpay.com%3a443%2forder%2fcancel%3forderId%3d00d11005-d30f-405d-b8d5-917a8ab78ba0&redirectConfirmUrl=https%3a%2f%2fapi-ut.quadpay.com%2forder%2fcomplete&metadata.confirmUrl=https%3a%2f%2fglobal-api.sand.au.edge.zip.co%3a443%2fmerchant%2fcallback%3fredirect%3dhttps%253A%252F%252Flocalhost%252Fzip_order_complete%26region%3dus%26ppStatus%3dsuccess%26token%3d00d11005-d30f-405d-b8d5-917a8ab78ba0%26OrderStatus%3dApproved&metadata.cancelUrl=https%3a%2f%2fglobal-api.sand.au.edge.zip.co%3a443%2fmerchant%2fcallback%3fredirect%3dhttps%253A%252F%252Flocalhost%252Fzip_order_complete%26region%3dus%26ppStatus%3dcancelled%26token%3d00d11005-d30f-405d-b8d5-917a8ab78ba0%26OrderStatus%3dAbandoned&X-QP-Signature=OO2OzWfV6EU1sRxNH%2bPFoCHEfZNLEq5SUwkvQvehTlU%3d"
                    },
                    "type": {
                      "type": "string",
                      "example": "standard"
                    },
                    "created": {
                      "type": "string",
                      "example": "2022-02-28T17:01:22.699Z"
                    },
                    "state": {
                      "type": "string",
                      "example": "created"
                    }
                  }
                }
              }
            }
          }
        },
        "deprecated": false
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": false,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}
```