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

# Place Order

> Creates a cart and place an order with Full Cart API features

## Overview

Creates a new cart with Full Cart API features and places an order in a single operation. This endpoint supports complex product references including variant handles and product IDs.

## Authentication

<ParamField header="x-firmly-authorization" type="string" required>
  Device authentication token from Browser Session
</ParamField>

## Path Parameters

<ParamField path="domain" type="string" required>
  The merchant domain (e.g., "staging.luma.gift")
</ParamField>

## Query Parameters

<ParamField query="sse" default="false" type="string">
  Enable Server-Sent Events for real-time progress updates. Set to "true" to receive events.
</ParamField>

## Request Body

<ParamField body="encrypted_card" type="string" required>
  JWE-encrypted credit card data using the public key from [Get Public Key](/api-reference/payment/get-public-key) endpoint
</ParamField>

<ParamField body="billing_info" type="object" required>
  Billing address information (same structure as shipping\_info)
</ParamField>

<ParamField body="shipping_info" type="object" required>
  Shipping address information

  **Required fields:**

  * `first_name` (string): Customer's first name
  * `last_name` (string): Customer's last name
  * `email` (string): Email address
  * `phone` (string): Phone number
  * `address1` (string): Primary address line
  * `city` (string): City name
  * `state_or_province` (string): State/province code
  * `country` (string): Country name or code
  * `postal_code` (string): ZIP or postal code

  **Optional fields:**

  * `address2` (string): Secondary address line
  * `company` (string): Company name
</ParamField>

<ParamField body="items" type="array" required>
  Array of items to add to cart

  **Item structure:**

  * `add_to_cart_ref` (object, required): Product reference
    * `variant_id` (string, required): Variant identifier
    * `product_id` (string, optional): Product identifier
    * `variant_handles` (array\[string], optional): Variant handle path
  * `quantity` (number, required): Quantity to purchase (minimum: 1)
</ParamField>

<ParamField body="captcha_token" type="string">
  Captcha verification token when required by merchant
</ParamField>

## Response

Returns an order confirmation with Full Cart API structure including shipments and detailed line item information.

## Server-Sent Events

When `sse=true`, the endpoint streams progress events:

* `creating-cart` - Cart creation started
* `item-added` - Item added to cart (includes cart data)
* `shipping-updated` - Shipping info set (includes cart data)
* `order-placed` - Order successfully placed (includes order data)
* `error` - Error occurred (includes error details)

## Code Example

```javascript theme={null}
// Place order with complex product references
const response = await fetch('https://cc.firmly.work/api/v2/payment/domains/staging.luma.gift/place-order', {
  method: 'POST',
  headers: {
    'x-firmly-authorization': authToken,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    encrypted_card: encryptedCard,
    billing_info: billingInfo,
    shipping_info: {
      first_name: 'John',
      last_name: 'Smith',
      email: 'john@staging.luma.gift',
      phone: '2065551212',
      address1: '123 Main St',
      city: 'Seattle',
      state_or_province: 'WA',
      country: 'US',
      postal_code: '98101'
    },
    items: [
      {
        add_to_cart_ref: {
          variant_id: 'WS12-XS-Orange',
          product_id: 'WS12',
          variant_handles: ['radiant-tee', 'xs-orange']
        },
        quantity: 1
      }
    ]
  })
});

const order = await response.json();
```

## SSE Example

```javascript theme={null}
// With Server-Sent Events
const eventSource = new EventSource(
  'https://cc.firmly.work/api/v2/payment/domains/staging.luma.gift/place-order?sse=true',
  {
    method: 'POST',
    headers: {
      'x-firmly-authorization': authToken,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      encrypted_card: encryptedCard,
      billing_info: billingInfo,
      shipping_info: shippingInfo,
      items: items
    })
  }
);

eventSource.addEventListener('item-added', (event) => {
  const data = JSON.parse(event.data);
  console.log('Item added to cart:', data.cart);
});

eventSource.addEventListener('order-placed', (event) => {
  const data = JSON.parse(event.data);
  console.log('Order completed:', data.order.platform_order_number);
  eventSource.close();
});
```

## Error Responses

| Code                    | Description                      |
| ----------------------- | -------------------------------- |
| `ErrorInvalidInputBody` | Request validation failed        |
| `ErrorProductNotFound`  | Product reference not found      |
| `ErrorNotEnoughStock`   | Insufficient inventory           |
| `ErrorPaymentDeclined`  | Payment was declined             |
| `ErrorStoreUnavailable` | Merchant temporarily unavailable |

## Related Endpoints

* [Get Public Key](/api-reference/payment/get-public-key) - Get encryption key
* [Complete Order](/api-reference/payment/complete-order-v2) - Alternative flow with existing cart
* [Add Line Item](/api-reference/cart-management/add-line-item) - Add items individually