> ## 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.

# Simple Cart API Implementation

> Complete guide for standard e-commerce checkout

## 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:

<CardGroup cols={3}>
  <Card title="Firmly Application ID" icon="key">
    Your Application ID from Firmly (contact support if you don't have one)
  </Card>

  <Card title="Test Merchant Domain" icon="globe">
    Work with Firmly to enable your app ID for a specific test store
  </Card>

  <Card title="API Client" icon="terminal">
    cURL, Postman, or your preferred HTTP client
  </Card>
</CardGroup>

<Note>
  **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.
</Note>

### 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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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": "john@staging.luma.gift",
    "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:

```bash theme={null}
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:

```bash theme={null}
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": "john@staging.luma.gift",
      "address1": "123 Main St",
      "city": "Seattle",
      "postal_code": "98101",
      "state_or_province": "Washington",
      "country": "United States"
    }
  }'
```

### Complete Example Flow

<CodeGroup>
  ```javascript JavaScript theme={null}
  // 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: 'john@staging.luma.gift',
        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: 'john@staging.luma.gift',
          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);
  ```

  ```python Python theme={null}
  import requests

  # 1. Initialize session
  auth_response = requests.post(
      'https://api.firmly.work/api/v1/browser-session',
      headers={'x-firmly-app-id': 'YOUR_APP_ID'}
  )
  access_token = auth_response.json()['access_token']

  # 2. Add item to cart
  cart_response = requests.post(
      'https://api.firmly.work/api/v1/domains/staging.luma.gift/cart/line-items/WS12-XS-Orange/quantity/1',
      headers={'x-firmly-authorization': access_token}
  )

  # 3. Set shipping info
  shipping_response = requests.post(
      'https://api.firmly.work/api/v1/domains/staging.luma.gift/cart/shipping-info',
      headers={
          'x-firmly-authorization': access_token,
          'Content-Type': 'application/json'
      },
      json={
          'first_name': 'John',
          'last_name': 'Smith',
          'email': 'john@staging.luma.gift',
          'phone': '(555) 123-4567',
          'address1': '123 Main St',
          'city': 'Seattle',
          'postal_code': '98101',
          'state_or_province': 'Washington',
          'country': 'United States'
      }
  )

  # 4. Complete order
  order_response = requests.post(
      'https://cc.firmly.work/api/v1/payment/domains/staging.luma.gift/complete-order',
      headers={
          'x-firmly-authorization': access_token,
          'Content-Type': 'application/json'
      },
      json={
          'encrypted_card': encrypted_card_data,  # See payment docs for encryption
          'billing_info': {
              'first_name': 'John',
              'last_name': 'Smith',
              'email': 'john@staging.luma.gift',
              'address1': '123 Main St',
              'city': 'Seattle',
              'postal_code': '98101',
              'state_or_province': 'Washington',
              'country': 'United States'
          }
      }
  )

  order = order_response.json()
  print(f"Order completed: {order['platform_order_number']}")
  ```
</CodeGroup>

### API Structure

Simple Cart API uses a flat cart structure:

```json theme={null}
{
  "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

* [Handle Errors](/resources/error-codes) - Learn about error codes and retry strategies
* [Explore Cart Operations](/api-reference/simple-cart-api/cart/get-cart) - Deep dive into cart management endpoints
* [Payment Integration](/api-reference/payment/get-public-key) - Understand payment tokenization and processing