# Place a new order

> Submits a new order for processing.

Source: https://help.boltapp.com/api-reference/checkout-everywhere/callbacks/orders-place

`POST /orders`

## OpenAPI definition

This endpoint as it appears in the OpenAPI document, with every schema it references included.

```json
{
  "openapi": "3.2.0",
  "info": {
    "title": "Checkout Everywhere API Reference (Beta)",
    "version": "0.1.0"
  },
  "security": [
    {
      "ApiKey": []
    }
  ],
  "paths": {
    "/orders": {
      "post": {
        "summary": "Place a new order",
        "operationId": "orders.place",
        "description": "Submits a new order for processing.",
        "tags": [
          "Callbacks"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/x_bolt_hmac_sha256"
          },
          {
            "$ref": "#/components/parameters/idempotency_key"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/order"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/place_order_response"
                }
              }
            }
          },
          "422": {
            "description": "Order Placement Failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/error_response"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "x_bolt_hmac_sha256": {
        "name": "X-Bolt-Hmac-Sha256",
        "in": "header",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "HMAC SHA256 hash of the request body, encoded in Base64."
      },
      "idempotency_key": {
        "description": "A key that ensures `POST` and `PATCH` requests are only performed once.",
        "in": "header",
        "name": "Idempotency-Key",
        "required": true,
        "schema": {
          "type": "string"
        }
      }
    },
    "schemas": {
      "order": {
        "type": "object",
        "allOf": [
          {
            "$ref": "#/components/schemas/order_without_items"
          }
        ],
        "description": "An order submitted by a shopper.",
        "properties": {
          "items": {
            "type": "array",
            "description": "Items in the order.",
            "items": {
              "$ref": "#/components/schemas/order_item"
            }
          }
        },
        "additionalProperties": false
      },
      "order_without_items": {
        "type": "object",
        "description": "An order submitted by a shopper.",
        "properties": {
          "reference": {
            "type": "string",
            "description": "Bolt order identifier."
          },
          "billing_address": {
            "description": "Billing address.",
            "$ref": "#/components/schemas/address"
          },
          "shipping_address": {
            "description": "Shipping address.",
            "$ref": "#/components/schemas/address"
          },
          "shipping": {
            "type": "array",
            "description": "Shipping details for the order.",
            "items": {
              "$ref": "#/components/schemas/shipping"
            }
          },
          "total": {
            "$ref": "#/components/schemas/price_with_tax",
            "description": "Total order price inclusive of tax, along with tax details."
          },
          "metadata": {
            "type": "object",
            "description": "Additional metadata related to the order.",
            "additionalProperties": {
              "type": "string"
            }
          }
        },
        "additionalProperties": false
      },
      "address": {
        "type": "object",
        "description": "A representation of a shopper's address.",
        "properties": {
          "first_name": {
            "type": "string",
            "description": "The first name of the shopper."
          },
          "last_name": {
            "type": "string",
            "description": "The last name of the shopper."
          },
          "company": {
            "type": "string",
            "nullable": true,
            "description": "The company associated with this address."
          },
          "street_address1": {
            "type": "string",
            "description": "The street address associated with this address."
          },
          "street_address2": {
            "type": "string",
            "nullable": true,
            "description": "Any additional, optional, street address information associated with this address."
          },
          "locality": {
            "type": "string",
            "description": "The locality (e.g. city, town, etc...) associated with this address."
          },
          "postal_code": {
            "type": "string",
            "description": "The postal code associated with this address."
          },
          "region": {
            "type": "string",
            "nullable": true,
            "description": "The region or administrative area (e.g. state, province, county, etc...) associated with this address. For addresses in the USA, this should be the state code (e.g., CA for California, NY for New York)."
          },
          "country_code": {
            "type": "string",
            "description": "The country (in its ISO 3166 alpha-2 format) associated with this address."
          },
          "email": {
            "type": "string",
            "nullable": true,
            "description": "The email address associated with the address."
          },
          "phone": {
            "type": "string",
            "nullable": true,
            "description": "The phone number associated with the address."
          }
        },
        "additionalProperties": false
      },
      "shipping": {
        "type": "object",
        "description": "Shipping details for the order.",
        "properties": {
          "amount": {
            "$ref": "#/components/schemas/price_with_tax",
            "description": "Shipping price inclusive of tax, along with tax details."
          }
        },
        "additionalProperties": false
      },
      "price_with_tax": {
        "type": "object",
        "allOf": [
          {
            "$ref": "#/components/schemas/price"
          }
        ],
        "description": "Price inclusive of tax, along with tax details.",
        "properties": {
          "tax": {
            "$ref": "#/components/schemas/price"
          }
        },
        "additionalProperties": false
      },
      "price": {
        "type": "object",
        "description": "A monetary amount, i.e. a base unit amount and a supported currency.",
        "properties": {
          "units": {
            "type": "integer",
            "format": "int64",
            "description": "A monetary amount, represented in its base units (e.g. USD/EUR cents)."
          },
          "currency": {
            "type": "string",
            "description": "A supported currency.",
            "enum": [
              "USD"
            ]
          }
        },
        "additionalProperties": false
      },
      "order_item": {
        "type": "object",
        "description": "Individual item in an order.",
        "properties": {
          "product": {
            "$ref": "#/components/schemas/product_id"
          },
          "quantity": {
            "type": "integer",
            "format": "int32",
            "description": "Number of units of the product."
          },
          "total_amount": {
            "$ref": "#/components/schemas/price_with_tax",
            "description": "Total item price inclusive of tax, along with tax details."
          }
        },
        "additionalProperties": false
      },
      "product_id": {
        "type": "object",
        "description": "Product ID information.",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the product."
          },
          "variant_id": {
            "type": "string",
            "description": "Unique identifier (within the product) of the variant."
          }
        },
        "additionalProperties": false
      },
      "place_order_response": {
        "type": "object",
        "description": "Response structure after placing an order.",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the placed order."
          }
        },
        "additionalProperties": false
      },
      "error_response": {
        "type": "object",
        "properties": {
          "error": {
            "$ref": "#/components/schemas/error"
          }
        }
      },
      "error": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "format": "int64",
            "description": "For list of potential error codes please see https://help.boltapp.com/developers/error-codes/"
          },
          "data": {
            "$ref": "#/components/schemas/reasons"
          }
        }
      },
      "reasons": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/reason"
        }
      },
      "reason": {
        "type": "object",
        "description": "The reason for the error.",
        "properties": {
          "reason": {
            "type": "string",
            "example": "This product is out of stock."
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKey": {
        "type": "apiKey",
        "name": "X-Api-Key",
        "in": "header",
        "description": "API key provided on the Custom API Connector 'Integrations' page."
      }
    }
  }
}
```