Skip to main content

​
Simple Cart API Guide

The Simple Cart API provides streamlined checkout for standard shipping workflows. Perfect for merchants whose products don’t require special fulfillment, like scheduled delivery or installation.

​
When to Use Simple Cart API

Choose Simple Cart API when your integration:
  • Works with merchants selling standard-shipped items only
  • Doesn’t need split shipments for different fulfillment types
  • Requires quick implementation with minimal complexity
  • Doesn’t need addon services (warranties, protection plans)

​
Key Characteristics

What You Get:
  • Direct cart operations with flat response structure
  • Single shipping method for entire order
  • Straightforward checkout flow
  • All standard cart features (coupons, shipping options, etc.)
What You Don’t Get:
  • Split shipments (mixing standard shipping with scheduled delivery)
  • Addon services (warranties, protection plans, installation)
  • Multiple fulfillment types in one order
  • Per-item shipping configuration

​
Prerequisites

Before starting, ensure you have:

Firmly Application ID

Your Application ID from Firmly (contact support if you don’t have one)

Test Merchant Domain

Work with Firmly to enable your app ID for a specific test store

API Client

cURL, Postman, or your preferred HTTP client
Important: Before you can access a merchant’s store, Firmly must configure your app ID to work with that specific domain. Contact our team to set up access to your test merchant.

​
Quick Start Implementation

Build your first checkout with Simple Cart API in 30 minutes.

​
Step 1: Authenticate

Get a device token to identify your user’s session: 
curl -X POST https://api.firmly.work/api/v1/browser-session \
  -H "x-firmly-app-id: YOUR_APP_ID"
Save the access_token from the response - you’ll use it as x-firmly-authorization in all subsequent requests.

​
Step 2: Add Items to Cart

Add a product using its SKU: 
curl -X POST https://api.firmly.work/api/v1/domains/staging.luma.gift/cart/line-items/WS12-XS-Orange/quantity/1 \
  -H "x-firmly-authorization: YOUR_TOKEN"

​
Step 3: Set Shipping Information

Provide the shipping address to get available shipping methods: 
curl -X POST https://api.firmly.work/api/v1/domains/staging.luma.gift/cart/shipping-info \
  -H "x-firmly-authorization: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John",
    "last_name": "Smith",
    "email": "[email protected]",
    "phone": "(555) 123-4567",
    "address1": "123 Main St",
    "city": "Seattle",
    "postal_code": "98101",
    "state_or_province": "Washington",
    "country": "United States"
  }'
The response includes:
  • Updated cart totals with tax
  • Available shipping methods
  • Auto-selected cheapest shipping option

​
Step 4: Select Shipping Method (Optional)

If you want a different shipping method than the auto-selected one: 
curl -X POST https://api.firmly.work/api/v1/domains/staging.luma.gift/cart/shipping-method \
  -H "x-firmly-authorization: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"shipping_method": "express_2day"}'

​
Step 5: Complete the Order

Use the Payment API to finalize the purchase: 
curl -X POST https://api.firmly.work/api/v3/payment/staging.luma.gift/complete-order \
  -H "x-firmly-authorization: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "encrypted_card": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwia2lkIjoidjEifQ...",
    "billing_info": {
      "first_name": "John",
      "last_name": "Smith",
      "email": "[email protected]",
      "address1": "123 Main St",
      "city": "Seattle",
      "postal_code": "98101",
      "state_or_province": "Washington",
      "country": "United States"
    }
  }'

​
Complete Example Flow

// 1. Initialize session
const authResponse = await fetch('https://api.firmly.work/api/v1/browser-session', {
  method: 'POST',
  headers: { 'x-firmly-app-id': 'YOUR_APP_ID' }
});
const { access_token } = await authResponse.json();

// 2. Add item to cart
const cartResponse = await fetch(
  'https://api.firmly.work/api/v1/domains/staging.luma.gift/cart/line-items/WS12-XS-Orange/quantity/1',
  {
    method: 'POST',
    headers: { 'x-firmly-authorization': access_token }
  }
);

// 3. Set shipping info
const shippingResponse = await fetch(
  'https://api.firmly.work/api/v1/domains/staging.luma.gift/cart/shipping-info',
  {
    method: 'POST',
    headers: {
      'x-firmly-authorization': access_token,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      first_name: 'John',
      last_name: 'Smith',
      email: '[email protected]',
      phone: '(555) 123-4567',
      address1: '123 Main St',
      city: 'Seattle',
      postal_code: '98101',
      state_or_province: 'Washington',
      country: 'United States'
    })
  }
);

// 4. Complete order
const orderResponse = await fetch(
  'https://cc.firmly.work/api/v1/payment/domains/staging.luma.gift/complete-order',
  {
    method: 'POST',
    headers: {
      'x-firmly-authorization': access_token,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      encrypted_card: encryptedCardData, // See payment docs for encryption
      billing_info: {
        // Same as shipping for this example
        first_name: 'John',
        last_name: 'Smith',
        email: '[email protected]',
        address1: '123 Main St',
        city: 'Seattle',
        postal_code: '98101',
        state_or_province: 'Washington',
        country: 'United States'
      }
    })
  }
);

const order = await orderResponse.json();
console.log('Order completed:', order.platform_order_number);

​
API Structure

Simple Cart API uses a flat cart structure: 
{
  "cart_id": "1e43868c-d4a5-418c-bd6b-5fff043550d2",
  "line_items": [
    {
      "line_item_id": "1ee530e1-063d-4e07-afb2-e7e65245977e",
      "sku": "WS12-XS-Orange",
      "quantity": 1,
      "price": { "value": 22.00, "currency": "USD" }
    }
  ],
  "shipping_method": {
    "sku": "standard_ground",
    "description": "Standard Ground (5-7 days)",
    "price": { "value": 9.99, "currency": "USD" }
  },
  "total": { "value": 31.99, "currency": "USD" }
}

​
Available Endpoints

​
Cart Operations

  • GET /api/v1/domains/{domain}/cart - Get current cart
  • POST /api/v1/domains/{domain}/cart/{product_id} - Add item to cart
  • PUT /api/v1/domains/{domain}/cart/{line_item_id} - Update quantity
  • DELETE /api/v1/domains/{domain}/cart - Clear cart

​
Checkout Flow

  • POST /api/v1/domains/{domain}/checkout/shipping-info - Set shipping address
  • GET /api/v1/domains/{domain}/checkout/shipping-rates - Get shipping options
  • POST /api/v1/domains/{domain}/checkout/shipping-method - Select shipping
  • POST /api/v3/payment/{domain}/complete-order - Complete purchase

​
Error Handling

Common errors and their meanings:
  • ErrorCartNotFound - Cart session expired
  • ErrorProductNotFound - Invalid product ID
  • ErrorNotEnoughStock - Item out of stock
  • ErrorCountryNotSupported - Shipping country not available
  • CreditCardDeclined - Payment failed

​
Perfect For

  • Apparel & Accessories - Everything ships standard
  • Books & Media - Uniform shipping methods
  • Consumer Electronics - Small items, standard delivery
  • Beauty Products - No special handling needed
  • Digital Goods - With physical components

​
Next Steps