> ## Documentation Index
> Fetch the complete documentation index at: https://docs.launchmystore.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Order

> Create a new order

# Create Order

Creates a new order programmatically. This is useful for importing orders from external systems or creating orders on behalf of customers.

<Note>
  The new order is always created with `status: "pending"`. Totals
  (`subtotal_price` / `total_price`) are derived purely from each line
  item's `price × quantity` — there is **no** inventory deduction, no
  discount-code resolution, and no tax/shipping calculation on this
  endpoint. Send a `price` on each line item if you need a non-zero total.
</Note>

## Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.launchmystore.io/api/v1/orders.json" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "line_items": [
        {
          "variant_id": "var_xyz789",
          "quantity": 2,
          "price": 2500
        }
      ],
      "customer": {
        "email": "customer@example.com"
      },
      "shipping_address": {
        "first_name": "John",
        "last_name": "Doe",
        "address1": "123 Main St",
        "city": "New York",
        "province": "NY",
        "country": "US",
        "zip": "10001"
      },
      "note": "Imported from external system"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.launchmystore.io/api/v1/orders.json', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      line_items: [
        {
          variant_id: 'var_xyz789',
          quantity: 2,
          price: 2500
        }
      ],
      customer: {
        email: 'customer@example.com'
      },
      shipping_address: {
        first_name: 'John',
        last_name: 'Doe',
        address1: '123 Main St',
        city: 'New York',
        province: 'NY',
        country: 'US',
        zip: '10001'
      },
      note: 'Imported from external system'
    })
  });
  ```
</CodeGroup>

## Body Parameters

Any field not listed below is ignored (stripped before the order is created).

<ParamField body="line_items" type="array" required>
  Array of line items for the order. Must contain at least one item.

  <Expandable title="Line Item Object">
    <ParamField body="product_id" type="string" required>
      Product ID.
    </ParamField>

    <ParamField body="variant_id" type="string">
      Product variant ID.
    </ParamField>

    <ParamField body="quantity" type="integer" required>
      Quantity to order (minimum `1`).
    </ParamField>

    <ParamField body="price" type="number">
      Price per item. Used directly to compute the order subtotal
      (`price × quantity`). If omitted, the item contributes `0` to the total.
    </ParamField>

    <ParamField body="title" type="string">
      Item title to store on the line.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="customer" type="object">
  Customer information. `customer.email` becomes the order email and the
  customer name is derived from `first_name` / `last_name`.

  <Expandable title="Customer Object">
    <ParamField body="id" type="string">Existing customer ID.</ParamField>
    <ParamField body="email" type="string">Customer email.</ParamField>
    <ParamField body="first_name" type="string">First name.</ParamField>
    <ParamField body="last_name" type="string">Last name.</ParamField>
    <ParamField body="phone" type="string">Phone number.</ParamField>
  </Expandable>
</ParamField>

<ParamField body="shipping_address" type="object">
  Shipping address for the order. Used to populate the order's address,
  city, state, country, ZIP and phone.

  <Expandable title="Address Object">
    <ParamField body="first_name" type="string">First name</ParamField>
    <ParamField body="last_name" type="string">Last name</ParamField>
    <ParamField body="address1" type="string">Street address line 1</ParamField>
    <ParamField body="address2" type="string">Street address line 2</ParamField>
    <ParamField body="city" type="string">City</ParamField>
    <ParamField body="province" type="string">State/Province</ParamField>
    <ParamField body="province_code" type="string">Province code</ParamField>
    <ParamField body="country" type="string">Country</ParamField>
    <ParamField body="country_code" type="string">Country code</ParamField>
    <ParamField body="zip" type="string">Postal/ZIP code</ParamField>
    <ParamField body="phone" type="string">Phone number</ParamField>
  </Expandable>
</ParamField>

<ParamField body="billing_address" type="object">
  Billing address. Same shape as `shipping_address`.
</ParamField>

<ParamField body="note" type="string">
  Order note.
</ParamField>

<ParamField body="tags" type="array">
  Array of tag strings. Accepted by the request but not currently persisted.
</ParamField>

## Response

On success (`201 Created`) the created order is returned under `order`,
including its line items. The order is created with
`financial_status: "pending"` and `fulfillment_status: "unfulfilled"`.
Money fields are decimal strings; there is no top-level `status` field.

## Example Response

```json theme={null}
{
  "order": {
    "id": "ord_new456",
    "order_number": 1002,
    "email": "customer@example.com",
    "financial_status": "pending",
    "fulfillment_status": "unfulfilled",
    "subtotal_price": "50.00",
    "total_price": "50.00",
    "line_items": [
      {
        "id": "li_new123",
        "variant_id": "var_xyz789",
        "title": "Classic T-Shirt",
        "quantity": 2,
        "price": "25.00",
        "line_price": "50.00"
      }
    ],
    "shipping_address": {
      "first_name": "John",
      "last_name": "Doe",
      "address1": "123 Main St",
      "city": "New York",
      "province": "NY",
      "country": "US",
      "zip": "10001"
    },
    "created_at": "2024-01-25T10:00:00Z",
    "updated_at": "2024-01-25T10:00:00Z"
  }
}
```

Errors are returned as a standard `{ errors }` body:

```json theme={null}
{
  "errors": {
    "base": ["line_items should not be empty"]
  }
}
```

## Error Codes

| Status | Description                                                                                    |
| ------ | ---------------------------------------------------------------------------------------------- |
| `400`  | Invalid request body (e.g. `line_items` empty, or a line item missing `product_id`/`quantity`) |
| `401`  | Invalid or missing access token                                                                |
| `403`  | App doesn't have the `write_orders` scope                                                      |
| `500`  | Unexpected server error while creating the order                                               |