Skip to main content
POST
/
api
/
v2
/
payment
/
domains
/
{domain}
/
place-order
Place Order
curl --request POST \
  --url https://cc.firmly.work/api/v2/payment/domains/{domain}/place-order \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-firmly-authorization: <x-firmly-authorization>' \
  --data '
{
  "encrypted_card": "<string>",
  "billing_info": {},
  "shipping_info": {},
  "items": [
    {}
  ],
  "captcha_token": "<string>"
}
'

​
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

​
x-firmly-authorization
string
required
Device authentication token from Browser Session

​
Path Parameters

​
domain
string
required
The merchant domain (e.g., “staging.luma.gift”)

​
Query Parameters

​
sse
string
default:"false"
Enable Server-Sent Events for real-time progress updates. Set to “true” to receive events.

​
Request Body

​
encrypted_card
string
required
JWE-encrypted credit card data using the public key from Get Public Key endpoint
​
billing_info
object
required
Billing address information (same structure as shipping_info)
​
shipping_info
object
required
Shipping address informationRequired 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
​
items
array
required
Array of items to add to cartItem 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)
​
captcha_token
string
Captcha verification token when required by merchant

​
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

// 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

// 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

CodeDescription
ErrorInvalidInputBodyRequest validation failed
ErrorProductNotFoundProduct reference not found
ErrorNotEnoughStockInsufficient inventory
ErrorPaymentDeclinedPayment was declined
ErrorStoreUnavailableMerchant temporarily unavailable