# Order Create Endpoint

#### Structure

##### Order

<table border="1" id="bkmrk-name-type-descriptio" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Type**  
</td><td>**Description**  
</td><td>**Required**  
</td></tr><tr><td>`id`</td><td>int</td><td>The id for the order</td><td>No</td></tr><tr><td>`reference`</td><td>string</td><td>The **unique** reference for the order</td><td>Yes</td></tr><tr><td>`status_id`</td><td>int</td><td>The status id of the order, can also be resolved from `state`</td><td>If `ordered_at` is not null</td></tr><tr><td>`state`</td><td>string</td><td>Alternative to passing `status_id`, resolves the first status with the specified state</td><td>No</td></tr><tr><td>`customer_id`</td><td>int</td><td>The id of the customer that placed the order</td><td>No</td></tr><tr><td>`email`</td><td>string</td><td>The email of the customer that placed the order</td><td>No</td></tr><tr><td>`subtotal.amount`</td><td>float</td><td>The subtotal of the order **excluding tax** (in pence not pounds)</td><td>No</td></tr><tr><td>`subtotal.tax`</td><td>float</td><td>The subtotal tax for the order (in pence not pounds)</td><td>No</td></tr><tr><td>`shipping.amount`</td><td>float</td><td>The shipping of the order **excluding tax** (in pence not pounds)</td><td>No</td></tr><tr><td>`shipping.tax`</td><td>float</td><td>The shipping tax for the order (in pence not pounds)</td><td>No</td></tr><tr><td>`discount.amount`</td><td>float</td><td>The discount of the order **excluding tax** (in pence not pounds)</td><td>No</td></tr><tr><td>`discount.tax`</td><td>float</td><td>The discount tax for the order (in pence not pounds)</td><td>No</td></tr><tr><td>`surcharge.amount`</td><td>float</td><td>The surcharge of the order **excluding tax** (in pence not pounds)</td><td>No</td></tr><tr><td>`surcharge.tax`</td><td>float</td><td>The surcharge tax for the order (in pence not pounds)</td><td>No</td></tr><tr><td>`shipping_method_id`</td><td>int</td><td>The shipping method id of the order</td><td>No</td></tr><tr><td>`currency`</td><td>string</td><td>The currency of the order, (defaults to store default if not provided)</td><td>No</td></tr><tr><td>`exchange_rate`</td><td>float</td><td>The exchange rate of the order (derives from currency if not supplied)</td><td>No</td></tr><tr><td>`shipping_address`</td><td>object</td><td>The [Shipping Address](https://support.aerocommerce.com/books/api/page/order-create-endpoint#bkmrk-shipping-address) for the order</td><td>No</td></tr><tr><td>`billing_address `</td><td>object</td><td>The [Billing Address](https://support.aerocommerce.com/books/api/page/order-create-endpoint#bkmrk-billing-address) for the order</td><td>No</td></tr><tr><td>`ip`</td><td>string</td><td>The ip of the order</td><td>No</td></tr><tr><td>`channel`</td><td>string</td><td>The channel of the order</td><td>No</td></tr><tr><td>`subscription_id`</td><td>int</td><td>The subscription id of the order</td><td>No</td></tr><tr><td>`notify`</td><td>boolean</td><td>Whether the order notifications are activated (defaults to `true`)</td><td>No</td></tr><tr><td>`buy_items`</td><td>boolean</td><td>Whether the order items stock should be mutated. If false then `OrderItemBought` event will not be emit (defaults to `true`)</td><td>No</td></tr><tr><td>`ordered_at`</td><td>timestamp</td><td>When the order was ordered</td><td>No</td></tr><tr><td>`deliver_on`</td><td>timestamp</td><td>When the order should be delivered</td><td>No</td></tr><tr><td>`items`</td><td>array</td><td>An array of [Order Item](https://support.aerocommerce.com/books/api/page/order-create-endpoint#bkmrk-order-item) objects</td><td>Yes</td></tr><tr><td>`payments`</td><td>array</td><td>An array of [Payment](https://support.aerocommerce.com/books/api/page/order-create-endpoint#bkmrk-payment) objects</td><td>No</td></tr><tr><td>`fulfillments`</td><td>array</td><td>An array of [Fulfillment](https://support.aerocommerce.com/books/api/page/order-create-endpoint#bkmrk-fulfillment) objects</td><td>No</td></tr><tr><td>`comments`</td><td>array</td><td>An array of [Comment](https://support.aerocommerce.com/books/api/page/order-create-endpoint#bkmrk-comment) objects</td><td>No</td></tr><tr><td>`additional_attributes`</td><td>array</td><td>An array of [Additional Attribute](https://support.aerocommerce.com/books/api/page/order-create-endpoint#bkmrk-additional-attribute) objects</td><td>No</td></tr></tbody></table>

<p class="callout info">If no `subtotal.amount` or `subtotal.tax` is passed their values will be set to the sum of the items `price.amount` \* `quantity` &amp; `price.tax` \* `quantity` respectively.</p>

<p class="callout info">If no `discount.amount` or `discount.tax` is passed their values will be set to the sum of the items `discount.amount` &amp; `discount.tax` respectively.</p>

##### Shipping Address

<table border="1" id="bkmrk-name-type-descriptio-1" style="border-collapse: collapse; width: 100%; height: 635.516px;"><colgroup><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col></colgroup><tbody><tr style="height: 29.7969px;"><td style="height: 29.7969px;">**Name**  
</td><td style="height: 29.7969px;">**Type**  
</td><td style="height: 29.7969px;">**Description**  
</td><td style="height: 29.7969px;">**Required**  
</td></tr><tr style="height: 46.5938px;"><td style="height: 46.5938px;">`first_name`</td><td style="height: 46.5938px;">string</td><td style="height: 46.5938px;">The first name for the shipping address</td><td style="height: 46.5938px;">Yes</td></tr><tr style="height: 46.5938px;"><td style="height: 46.5938px;">`last_name`</td><td style="height: 46.5938px;">string</td><td style="height: 46.5938px;">The last name for the shipping address</td><td style="height: 46.5938px;">Yes</td></tr><tr style="height: 46.5938px;"><td style="height: 46.5938px;">`company`</td><td style="height: 46.5938px;">string</td><td style="height: 46.5938px;">The company for the shipping address</td><td style="height: 46.5938px;">No</td></tr><tr style="height: 46.5938px;"><td style="height: 46.5938px;">`mobile`</td><td style="height: 46.5938px;">string</td><td style="height: 46.5938px;">The mobile number for the shipping address</td><td style="height: 46.5938px;">No</td></tr><tr style="height: 46.5938px;"><td style="height: 46.5938px;">`phone`</td><td style="height: 46.5938px;">string</td><td style="height: 46.5938px;">The phone number for the shipping address</td><td style="height: 46.5938px;">No</td></tr><tr style="height: 46.5938px;"><td style="height: 46.5938px;">`line_1`</td><td style="height: 46.5938px;">string</td><td style="height: 46.5938px;">The first line for the shipping address</td><td style="height: 46.5938px;">Yes</td></tr><tr style="height: 46.5938px;"><td style="height: 46.5938px;">`line_2`</td><td style="height: 46.5938px;">string</td><td style="height: 46.5938px;">The second line for the shipping address</td><td style="height: 46.5938px;">No</td></tr><tr style="height: 46.5938px;"><td style="height: 46.5938px;">`city`</td><td style="height: 46.5938px;">string</td><td style="height: 46.5938px;">The city for the shipping address</td><td style="height: 46.5938px;">Yes</td></tr><tr style="height: 46.5938px;"><td style="height: 46.5938px;">`zone`</td><td style="height: 46.5938px;">string</td><td style="height: 46.5938px;">The zone code for the shipping address</td><td style="height: 46.5938px;">No</td></tr><tr style="height: 46.5938px;"><td style="height: 46.5938px;">`postcode`</td><td style="height: 46.5938px;">string</td><td style="height: 46.5938px;">The postcode for the shipping address</td><td style="height: 46.5938px;">Yes</td></tr><tr style="height: 46.5938px;"><td style="height: 46.5938px;">`country`</td><td style="height: 46.5938px;">string</td><td style="height: 46.5938px;">The country code for the shipping address</td><td style="height: 46.5938px;">No</td></tr><tr style="height: 46.5938px;"><td style="height: 46.5938px;">`reference`</td><td style="height: 46.5938px;">string</td><td style="height: 46.5938px;">The **unique** reference for the shipping address</td><td style="height: 46.5938px;">No</td></tr><tr style="height: 46.5938px;"><td style="height: 46.5938px;">`eori_number`</td><td style="height: 46.5938px;">string</td><td style="height: 46.5938px;">The EORI number for the shipping address</td><td style="height: 46.5938px;">No</td></tr></tbody></table>

##### Billing Address

<table border="1" id="bkmrk-name-type-descriptio-2" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Type**  
</td><td>**Description**  
</td><td>**Required**  
</td></tr><tr><td>`first_name`</td><td>string</td><td>The first name for the billing address</td><td>Yes</td></tr><tr><td>`last_name`</td><td>string</td><td>The last name for the billing address</td><td>Yes</td></tr><tr><td>`company`</td><td>string</td><td>The company for the billing address</td><td>No</td></tr><tr><td>`mobile`</td><td>string</td><td>The mobile number for the billing address</td><td>No</td></tr><tr><td>`phone`</td><td>string</td><td>The phone number for the billing address</td><td>No</td></tr><tr><td>`line_1`</td><td>string</td><td>The first line for the billing address</td><td>Yes</td></tr><tr><td>`line_2`</td><td>string</td><td>The second line for the billing address</td><td>No</td></tr><tr><td>`city`</td><td>string</td><td>The city for the billing address</td><td>Yes</td></tr><tr><td>`zone`</td><td>string</td><td>The zone code for the billing address</td><td>No</td></tr><tr><td>`postcode`</td><td>string</td><td>The postcode for the billing address</td><td>Yes</td></tr><tr><td>`country`</td><td>string</td><td>The country code for the billing address</td><td>No</td></tr><tr><td>`reference`</td><td>string</td><td>The **unique** reference for the billing address</td><td>No</td></tr><tr><td>`eori_number`</td><td>string</td><td>The EORI number for the billing address</td><td>No</td></tr></tbody></table>

##### Order Item

<table border="1" id="bkmrk-name-type-descriptio-3" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Type**  
</td><td>**Description**  
</td><td>**Required**  
</td></tr><tr><td>`key`</td><td>string</td><td>The unique key for the order item</td><td>No</td></tr><tr><td>`variant_id`</td><td>int</td><td>The variant id of the buyable</td><td>No</td></tr><tr><td>`product_id`</td><td>string</td><td>The product id of the buyable (resolves first variant unless variant\_id is provided)</td><td>No</td></tr><tr><td>`buyable_type`</td><td>string</td><td>The buyable type of the order item</td><td>Not required if any of:  
`sku`/`variant_id`/`product_id` are provided</td></tr><tr><td>`buyable_id`</td><td>int</td><td>The buyable id of the order item</td><td>Not required if any of:  
`sku`/`variant_id`/`product_id` are provided</td></tr><tr><td>`name`</td><td>string</td><td>The name for the order item</td><td>Conditional `*`</td></tr><tr><td>`url`</td><td>string</td><td>The url for the order item</td><td>No</td></tr><tr><td>`sku`</td><td>string</td><td>The sku for the order item, can be used to resolve buyable</td><td>Conditional `*`</td></tr><tr><td>`reference`</td><td>string</td><td>The **unique** reference for the order item</td><td>No</td></tr><tr><td>`manufacturer_id`</td><td>int</td><td>The manufacturer id for the order item</td><td>No</td></tr><tr><td>`image`</td><td>string</td><td>The image for the order item</td><td>No</td></tr><tr><td>`options`</td><td>array</td><td>The options for the order item</td><td>No</td></tr><tr><td>`shippable`</td><td>boolean</td><td>Whether the order item is shippable</td><td>No</td></tr><tr><td>`quantity`</td><td>int</td><td>The quantity for the order item</td><td>Yes</td></tr><tr><td>`price.amount`</td><td>float</td><td>The **unit** price of the order item **excluding tax** (in pence not pounds)</td><td>Yes</td></tr><tr><td>`price.tax`</td><td>float</td><td>The **unit** tax for the order item (in pence not pounds)</td><td>Yes</td></tr><tr><td>`discount.amount`</td><td>float</td><td>The **total** discount of the order item **excluding tax** (in pence not pounds)</td><td>No</td></tr><tr><td>`discount.tax`</td><td>float</td><td>The **total** discount tax for the order item (in pence not pounds)</td><td>No</td></tr><tr><td>`full_price.amount`</td><td>float</td><td>The **unit** full price (including extras) of the order item **excluding tax** (in pence not pounds)</td><td>No</td></tr><tr><td>`full_price.tax`</td><td>float</td><td>The **unit** full tax (including extras) for the order item (in pence not pounds)</td><td>No</td></tr><tr><td>`cost_price.amount`</td><td>float</td><td>The **unit** cost price of the order item **excluding tax** (in pence not pounds)</td><td>No</td></tr><tr><td>`cost_price.currency`</td><td>string</td><td>The currency code for the cost price</td><td>No</td></tr><tr><td>`weight`</td><td>float</td><td>The weight for the order item</td><td>No</td></tr><tr><td>`weight_unit`</td><td>float</td><td>The weight unit for the order item, defaults to stores normalized  
weight unit if not passed</td><td>No</td></tr><tr><td>`volume`</td><td>float</td><td>The volume for the order item</td><td>No</td></tr><tr><td>`volume_unit`</td><td>float</td><td>The volume unit for the order item, defaults to stores normalized  
volume unit if not passed</td><td>No</td></tr><tr><td>`tag_ids`</td><td>array</td><td>The tag ids for the order item</td><td>No</td></tr><tr><td>`hs`</td><td>string</td><td>The HS code for the order item</td><td>No</td></tr><tr><td>`origin_country`</td><td>string</td><td>The origin country code for the order item</td><td>No</td></tr><tr><td>`subscription_plan_id`</td><td>int</td><td>The subscription plan id for the order item</td><td>No</td></tr><tr><td>`goods_description`</td><td>string</td><td>The goods description for the order item</td><td>No</td></tr></tbody></table>

`*` If no buyable can be resolved from the given data, the `sku` is required - as is the `name`.

<p class="callout info">`price`, `discount` &amp; `full_price` all support an un-nested price including tax being passed, see [Price Conventions](https://support.aerocommerce.com/link/726#bkmrk-price-conventions).</p>

##### Payment

<table border="1" id="bkmrk-name-type-descriptio-4" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Type**  
</td><td>**Description**  
</td><td>**Required**  
</td></tr><tr><td>`method_id`</td><td>int</td><td>The payment method id of the payment</td><td>Not required if `driver` is passed</td></tr><tr><td>`driver`</td><td>string</td><td>Payment driver used to resolve `method_id`</td><td>No</td></tr><tr><td>`reference`</td><td>string</td><td>The reference for the payment, if not specified a uuid will be generated</td><td>No</td></tr><tr><td>`state`</td><td>string</td><td>The state for the payment, if not specified the captured state will be used</td><td>No</td></tr><tr><td>`amount`</td><td>float</td><td>The total amount for the payment</td><td>Yes</td></tr></tbody></table>

**Valid states:** failed, pending, authorized, partially captured, captured, partially refunded, refunded, canceled, errored

##### Fulfillment

<table border="1" id="bkmrk-name-type-descriptio-5" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Type**  
</td><td>**Description**  
</td><td>**Required**  
</td></tr><tr><td>`id`</td><td>int</td><td>The id for the fulfillment</td><td>No</td></tr><tr><td>`reference`</td><td>string</td><td>The reference for the fulfillment</td><td>No</td></tr><tr><td>`state`</td><td>string</td><td>The state of the fulfillment (defaults to method's default if not passed)</td><td>No</td></tr><tr><td>`method`</td><td>int| string</td><td>The fulfillment method's id, name or driver (defaults to orders' default if not passed)</td><td>No</td></tr><tr><td>`tracking_code`</td><td>string</td><td>The tracking code for the fulfillment</td><td>No</td></tr><tr><td>`tracking_url`</td><td>url</td><td>The tracking url for the fulfillment</td><td>No</td></tr><tr><td>`weight`</td><td>float</td><td>The total weight of the fulfillment (calculated from items if not passed)</td><td>No</td></tr><tr><td>`weight_unit`</td><td>string</td><td>The weight unit (defaults to store's default if not provided)</td><td>No</td></tr><tr><td>`volume`</td><td>float</td><td>The total volume of the fulfillment (calculated from items if not passed)</td><td>No</td></tr><tr><td>`volume_unit`</td><td>string</td><td>The volume unit (defaults to store's default if not provided)</td><td>No</td></tr><tr><td>`delivery_note`</td><td>string</td><td>The delivery note for the fulfillment</td><td>No</td></tr><tr><td>`notify`</td><td>boolean</td><td>Whether the fulfillment notifications are activated (defaults to `true`)</td><td>No</td></tr><tr><td>`dispatched_at`</td><td>timestamp</td><td>The dispatched at of the fulfillment</td><td>No</td></tr><tr><td>`items`</td><td>array</td><td>An array of [Fullfillment Item](https://support.aerocommerce.com/books/api/page/order-create-endpoint#bkmrk-fulfillment-item) objects (if not passed every fulfillable item is fulfilled)</td><td>No</td></tr></tbody></table>

##### Fulfillment Item

<table border="1" id="bkmrk-name-type-descriptio-6" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Type**  
</td><td>**Description**  
</td><td>**Required**  
</td></tr><tr><td>`sku`</td><td>string</td><td>The sku of the order item to be fulfilled</td><td>Yes</td></tr><tr><td>`quantity`</td><td>int</td><td>The quantity to be fulfilled (defaults to max possible)</td><td>No</td></tr><tr><td>`weight`</td><td>float</td><td>The weight of the item (uses order item's weight if not passed)</td><td>No</td></tr><tr><td>`weight_unit`</td><td>string</td><td>The weight unit (defaults to store's default if not provided)</td><td>No</td></tr><tr><td>`volume`</td><td>float</td><td>The volume of the fulfillment (uses order item's volume if not passed)</td><td>No</td></tr><tr><td>`volume_unit`</td><td>string</td><td>The volume unit (defaults to store's default if not provided)</td><td>No</td></tr></tbody></table>

##### Comment

<table border="1" id="bkmrk-name-type-descriptio-7" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Type**  
</td><td>**Description**  
</td><td>**Required**  
</td></tr><tr><td>`id`</td><td>int</td><td>The id for the comment</td><td>No</td></tr><tr><td>`admin`</td><td>int|string</td><td>The id or email of the admin</td><td>No</td></tr><tr><td>`message`</td><td>string</td><td>The comment message</td><td>Yes</td></tr><tr><td>`customer_facing`</td><td>boolean</td><td>Whether the comment is customer facing (default: `false`)</td><td>No</td></tr><tr><td>`created_at`</td><td>timestamp</td><td>The date the comment was created (defaults to now)</td><td>No</td></tr></tbody></table>

##### Additional Attribute

<table border="1" id="bkmrk-name-type-descriptio-8" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Type**  
</td><td>**Description**  
</td><td>**Required**  
</td></tr><tr><td>`key`</td><td>string</td><td>The key of the additional attribute</td><td>Yes</td></tr><tr><td>`value`</td><td>string</td><td>The value of the additional attribute</td><td>Yes</td></tr></tbody></table>

#### Example Request

```
POST /api/orders
```

```json
{
    "reference": "ABC123",
    "email": "testing@gmail.com",
    "subtotal": {
        "amount": 84166.67,
        "tax": 16833.33
    },
    "shipping": {
        "amount": 83.33,
        "tax": 16.67
    },
    "discount": {
        "amount": 8416.67,
        "tax": 1683.33
    },
    "ordered_at": "2023-09-01T09:29:41.000000Z",
    "currency": "GBP", 
    "status_id": 3, 
    "customer_id": 1, 
    "shipping_method_id": 1, 
    "notify": true, 
    "billing_address": { 
        "first_name": "Aero",
        "last_name": "Commerce",
        "company": "Aero Commerce", 
        "mobile": null, 
        "phone": null, 
        "line_1": "28-32 Albert Rd",
        "line_2": null, 
        "city": "Middlesbrough",
        "zone": null, 
        "postcode": "TS1 1QD",
        "reference": null, 
        "country": "GB", 
        "eori_number": null 
    },
    "shipping_address": {
        "first_name": "Aero",
        "last_name": "Commerce",
        "company": "Aero Commerce", 
        "mobile": null, 
        "phone": null, 
        "line_1": "28-32 Albert Rd",
        "line_2": null, 
        "city": "Middlesbrough",
        "zone": null, 
        "postcode": "TS1 1QD",
        "reference": null, 
        "country": "GB", 
        "eori_number": null 
    },
    "items": [
        {
            "variant_id": 1,
            "shippable": true,
            "quantity": 2,
            "price": {
                "amount": 42083.33,
                "tax": 8416.67
            },
            "discount": {
                "amount": 8416.67,
                "tax": 1683.33
            }
        }
    ],
    "payments": [
        {
            "driver": "cash",
            "amount": 91000
        }
    ],
    "comments": [
        {
            "admin": "admin@example.com",
            "message": "This is an API message",
            "created_at": "2025-09-01 09:29:41",
            "customer_facing": true
        }
    ]
}
```