Place Order

POST

api

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>"
}
'

import requests

url = "https://cc.firmly.work/api/v2/payment/domains/{domain}/place-order"

payload = {
    "encrypted_card": "<string>",
    "billing_info": {},
    "shipping_info": {},
    "items": [{}],
    "captcha_token": "<string>"
}
headers = {
    "x-firmly-authorization": "<x-firmly-authorization>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-firmly-authorization': '<x-firmly-authorization>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    encrypted_card: '<string>',
    billing_info: {},
    shipping_info: {},
    items: [{}],
    captcha_token: '<string>'
  })
};

fetch('https://cc.firmly.work/api/v2/payment/domains/{domain}/place-order', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://cc.firmly.work/api/v2/payment/domains/{domain}/place-order",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'encrypted_card' => '<string>',
    'billing_info' => [
        
    ],
    'shipping_info' => [
        
    ],
    'items' => [
        [
                
        ]
    ],
    'captcha_token' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "x-firmly-authorization: <x-firmly-authorization>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://cc.firmly.work/api/v2/payment/domains/{domain}/place-order"

	payload := strings.NewReader("{\n  \"encrypted_card\": \"<string>\",\n  \"billing_info\": {},\n  \"shipping_info\": {},\n  \"items\": [\n    {}\n  ],\n  \"captcha_token\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-firmly-authorization", "<x-firmly-authorization>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://cc.firmly.work/api/v2/payment/domains/{domain}/place-order")
  .header("x-firmly-authorization", "<x-firmly-authorization>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"encrypted_card\": \"<string>\",\n  \"billing_info\": {},\n  \"shipping_info\": {},\n  \"items\": [\n    {}\n  ],\n  \"captcha_token\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://cc.firmly.work/api/v2/payment/domains/{domain}/place-order")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-firmly-authorization"] = '<x-firmly-authorization>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"encrypted_card\": \"<string>\",\n  \"billing_info\": {},\n  \"shipping_info\": {},\n  \"items\": [\n    {}\n  ],\n  \"captcha_token\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

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

string

required

Device authentication token from Browser Session

Path Parameters

string

required

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

Query Parameters

string

default:"false"

Enable Server-Sent Events for real-time progress updates. Set to “true” to receive events.

Request Body

string

required

JWE-encrypted credit card data using the public key from Get Public Key endpoint

object

required

Billing address information (same structure as 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

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)

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

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

Get Public Key - Get encryption key
Complete Order - Alternative flow with existing cart
Add Line Item - Add items individually

⌘I

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>"
}
'

import requests

url = "https://cc.firmly.work/api/v2/payment/domains/{domain}/place-order"

payload = {
    "encrypted_card": "<string>",
    "billing_info": {},
    "shipping_info": {},
    "items": [{}],
    "captcha_token": "<string>"
}
headers = {
    "x-firmly-authorization": "<x-firmly-authorization>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-firmly-authorization': '<x-firmly-authorization>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    encrypted_card: '<string>',
    billing_info: {},
    shipping_info: {},
    items: [{}],
    captcha_token: '<string>'
  })
};

fetch('https://cc.firmly.work/api/v2/payment/domains/{domain}/place-order', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://cc.firmly.work/api/v2/payment/domains/{domain}/place-order",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'encrypted_card' => '<string>',
    'billing_info' => [
        
    ],
    'shipping_info' => [
        
    ],
    'items' => [
        [
                
        ]
    ],
    'captcha_token' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "x-firmly-authorization: <x-firmly-authorization>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://cc.firmly.work/api/v2/payment/domains/{domain}/place-order"

	payload := strings.NewReader("{\n  \"encrypted_card\": \"<string>\",\n  \"billing_info\": {},\n  \"shipping_info\": {},\n  \"items\": [\n    {}\n  ],\n  \"captcha_token\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-firmly-authorization", "<x-firmly-authorization>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://cc.firmly.work/api/v2/payment/domains/{domain}/place-order")
  .header("x-firmly-authorization", "<x-firmly-authorization>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"encrypted_card\": \"<string>\",\n  \"billing_info\": {},\n  \"shipping_info\": {},\n  \"items\": [\n    {}\n  ],\n  \"captcha_token\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://cc.firmly.work/api/v2/payment/domains/{domain}/place-order")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-firmly-authorization"] = '<x-firmly-authorization>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"encrypted_card\": \"<string>\",\n  \"billing_info\": {},\n  \"shipping_info\": {},\n  \"items\": [\n    {}\n  ],\n  \"captcha_token\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

Home

Core Concepts

Implementation Guides

Ask Agent SDK

API Reference

firmly Connect

Resources

Overview

Authentication

Path Parameters

Query Parameters

Request Body

Response

Server-Sent Events

Code Example

SSE Example

Error Responses

​Overview

​Authentication

​Path Parameters

​Query Parameters

​Request Body

​Response

​Server-Sent Events

​Code Example

​SSE Example

​Error Responses

​Related Endpoints

Overview

Authentication

Path Parameters

Query Parameters

Request Body

Response

Server-Sent Events

Code Example

SSE Example

Error Responses

Related Endpoints