Skip to main content
POST
/
api
/
v1
/
payment
/
domains
/
{domain}
/
place-order
Place Order
curl --request POST \
  --url https://cc.firmly.work/api/v1/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>"
}
'
{
  "cart_id": "<string>",
  "platform_order_number": "<string>",
  "cart_status": "<string>",
  "submitted_at": "<string>",
  "display_name": "<string>",
  "platform_id": "<string>",
  "shop_id": "<string>",
  "urls": {
    "thank_you_page": "<string>"
  },
  "line_items": [
    {
      "line_item_id": "<string>",
      "sku": "<string>",
      "quantity": 123,
      "description": "<string>",
      "price": {},
      "line_price": {},
      "image": {}
    }
  ],
  "shipping_info": {},
  "billing_info": {},
  "shipping_method": {},
  "payment_summary": {
    "payment_type": "<string>",
    "last_four": "<string>",
    "card_type": "<string>",
    "month": 123,
    "year": 123
  },
  "total": {},
  "sub_total": {},
  "shipping_total": {},
  "tax": {},
  "cart_discount": {}
}

​
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

​
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 cart. Each item must have:
​
captcha_token
string
Captcha verification token when required by merchant

​
Response

Returns a comprehensive order confirmation object including cart details, order information, and payment confirmation.
​
cart_id
string
Unique identifier for the cart
​
platform_order_number
string
The order number from the merchant platform
​
cart_status
string
Status of the cart (e.g., “submitted”)
​
submitted_at
string
ISO timestamp when the order was submitted
​
display_name
string
Merchant’s display name
​
platform_id
string
E-commerce platform identifier (e.g., “magento”, “shopify”)
​
shop_id
string
Merchant domain
​
urls
object
Relevant URLs for the order
​
line_items
array
Array of items in the order
​
shipping_info
object
Delivery address details
​
billing_info
object
Billing address details
​
shipping_method
object
Selected shipping method with pricing
​
payment_summary
object
Summary of payment method used
​
total
object
Grand total including all costs
​
sub_total
object
Subtotal before shipping and tax
​
shipping_total
object
Shipping cost
​
tax
object
Tax amount
​
cart_discount
object
Total discount applied

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

{
  "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
    }
  ]
}

​
Response Example

{
  "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

CodeDescription
ErrorInvalidInputBodyRequest validation failed
ErrorProductNotFoundVariant ID not found
ErrorNotEnoughStockInsufficient inventory
ErrorPaymentDeclinedPayment was declined
ErrorStoreUnavailableMerchant temporarily unavailable