> ## 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 places an order in a single operation

## Overview

Creates a new cart, add items, set shipping information, and place an order - all in one API call. This endpoint is ideal for simple checkout flows where you want to minimize API calls.

## 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. Each item must have:

  <Expandable title="Item Schema">
    <ResponseField name="variant_id" type="string" required>
      Product variant identifier from the catalog
    </ResponseField>

    <ResponseField name="quantity" type="number" required>
      Quantity to purchase (minimum: 1)
    </ResponseField>
  </Expandable>
</ParamField>

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

## Response

Returns a comprehensive order confirmation object including cart details, order information, and payment confirmation.

<ResponseField name="cart_id" type="string">
  Unique identifier for the cart
</ResponseField>

<ResponseField name="platform_order_number" type="string">
  The order number from the merchant platform
</ResponseField>

<ResponseField name="cart_status" type="string">
  Status of the cart (e.g., "submitted")
</ResponseField>

<ResponseField name="submitted_at" type="string">
  ISO timestamp when the order was submitted
</ResponseField>

<ResponseField name="display_name" type="string">
  Merchant's display name
</ResponseField>

<ResponseField name="platform_id" type="string">
  E-commerce platform identifier (e.g., "magento", "shopify")
</ResponseField>

<ResponseField name="shop_id" type="string">
  Merchant domain
</ResponseField>

<ResponseField name="urls" type="object">
  Relevant URLs for the order

  <Expandable title="URLs">
    <ResponseField name="thank_you_page" type="string">
      URL to the merchant's order confirmation page
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="line_items" type="array">
  Array of items in the order

  <Expandable title="Line Item Details">
    <ResponseField name="line_item_id" type="string">
      Unique identifier for the line item
    </ResponseField>

    <ResponseField name="sku" type="string">
      Product SKU
    </ResponseField>

    <ResponseField name="quantity" type="number">
      Quantity ordered
    </ResponseField>

    <ResponseField name="description" type="string">
      Product description
    </ResponseField>

    <ResponseField name="price" type="object">
      Unit price
    </ResponseField>

    <ResponseField name="line_price" type="object">
      Total price for this line item
    </ResponseField>

    <ResponseField name="image" type="object">
      Product image information
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="shipping_info" type="object">
  Delivery address details
</ResponseField>

<ResponseField name="billing_info" type="object">
  Billing address details
</ResponseField>

<ResponseField name="shipping_method" type="object">
  Selected shipping method with pricing
</ResponseField>

<ResponseField name="payment_summary" type="object">
  Summary of payment method used

  <Expandable title="Payment Summary">
    <ResponseField name="payment_type" type="string">
      Type of payment (e.g., "CreditCard")
    </ResponseField>

    <ResponseField name="last_four" type="string">
      Last four digits of the card
    </ResponseField>

    <ResponseField name="card_type" type="string">
      Card brand (e.g., "Visa", "Mastercard")
    </ResponseField>

    <ResponseField name="month" type="number">
      Card expiration month
    </ResponseField>

    <ResponseField name="year" type="number">
      Card expiration year
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total" type="object">
  Grand total including all costs
</ResponseField>

<ResponseField name="sub_total" type="object">
  Subtotal before shipping and tax
</ResponseField>

<ResponseField name="shipping_total" type="object">
  Shipping cost
</ResponseField>

<ResponseField name="tax" type="object">
  Tax amount
</ResponseField>

<ResponseField name="cart_discount" type="object">
  Total discount applied
</ResponseField>

## 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 SSE for progress updates
const eventSource = new EventSource(
  'https://cc.firmly.work/api/v1/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: {
        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: [
        {
          variant_id: 'WS12-XS-Orange',
          quantity: 2
        },
        {
          variant_id: 'MH07-XS-Gray',
          quantity: 1
        }
      ]
    })
  }
);

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

eventSource.addEventListener('error', (event) => {
  const error = JSON.parse(event.data).error;
  console.error('Order failed:', error.message);
});
```

## Request Example

<CodeGroup>
  ```json Request Body theme={null}
  {
    "encrypted_card": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwia2lkIjoidjEifQ...",
    "billing_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"
    },
    "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": [
      {
        "variant_id": "WS12-XS-Orange",
        "quantity": 2
      },
      {
        "variant_id": "MH07-XS-Gray",
        "quantity": 1
      }
    ]
  }
  ```

  ```javascript JavaScript theme={null}
  // Without SSE
  const response = await fetch('https://cc.firmly.work/api/v1/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: shippingInfo,
      items: [
        {
          variant_id: 'WS12-XS-Orange',
          quantity: 1
        }
      ]
    })
  });

  const order = await response.json();
  ```
</CodeGroup>

## Response Example

```json theme={null}
{
  "cart_id": "9cf76530-1344-420f-9ca6-c7a96fb6db45",
  "platform_order_number": "6800018416",
  "cart_status": "submitted",
  "submitted_at": "2024-07-22T18:58:25.000Z",
  "display_name": "LUMA By Firmly",
  "platform_id": "magento",
  "shop_id": "staging.luma.gift",
  "urls": {
    "thank_you_page": "https://staging.luma.gift/checkout/onepage/success/"
  },
  "line_items": [
    {
      "line_item_id": "3e66bef5-43f5-4a80-8957-91c5c8233163",
      "sku": "MT12",
      "quantity": 4,
      "description": "Cassius Sparring Tank",
      "price": {
        "currency": "USD",
        "value": 18,
        "number": 1800,
        "symbol": "$"
      },
      "line_price": {
        "currency": "USD",
        "value": 72,
        "number": 7200,
        "symbol": "$"
      },
      "image": {
        "url": "https://staging.luma.gift/pub/media/catalog/product/m/t/mt12-blue_main_1.jpg"
      }
    }
  ],
  "shipping_info": {
    "first_name": "John",
    "last_name": "Smith",
    "email": "john@staging.luma.gift",
    "phone": "(206) 555-1212",
    "address1": "123 Main St",
    "city": "Seattle",
    "state_or_province": "Washington",
    "country": "US",
    "postal_code": "98101"
  },
  "billing_info": {
    "first_name": "John",
    "last_name": "Smith",
    "email": "john@staging.luma.gift",
    "phone": "(206) 555-1212",
    "address1": "123 Main St",
    "city": "Seattle",
    "state_or_province": "Washington",
    "country": "US",
    "postal_code": "98101"
  },
  "shipping_method": {
    "id": "s2_2_day",
    "description": "2-Day Shipping",
    "price": {
      "currency": "USD",
      "value": 12,
      "number": 1200,
      "symbol": "$"
    }
  },
  "payment_summary": {
    "payment_type": "CreditCard",
    "last_four": "1111",
    "card_type": "Visa",
    "month": 6,
    "year": 2028
  },
  "total": {
    "currency": "USD",
    "value": 91.08,
    "number": 9108,
    "symbol": "$"
  },
  "sub_total": {
    "currency": "USD",
    "value": 72,
    "number": 7200,
    "symbol": "$"
  },
  "shipping_total": {
    "currency": "USD",
    "value": 12,
    "number": 1200,
    "symbol": "$"
  },
  "tax": {
    "currency": "USD",
    "value": 7.08,
    "number": 708,
    "symbol": "$"
  },
  "cart_discount": {
    "currency": "USD",
    "value": 0,
    "number": 0,
    "symbol": "$"
  }
}
```

## Error Responses

| Code                    | Description                      |
| ----------------------- | -------------------------------- |
| `ErrorInvalidInputBody` | Request validation failed        |
| `ErrorProductNotFound`  | Variant ID 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-v1) - Alternative flow with existing cart