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

# Choosing Your API

> Simple Cart API vs Full Cart API - Making the right choice

# Choosing Your API

Firmly offers two API options to match different integration needs. Both connect to the same merchant systems - the difference is in complexity and capabilities.

<Info>
  **New to Firmly?** This guide helps you choose between our Simple Cart API and Full Cart API. Most standard e-commerce integrations should start with Simple Cart API.
</Info>

## Quick Decision Guide

### Use Simple Cart API When:

**Your checkout needs:**

* All items will ship via standard methods
* Single shipping address per order
* One shipping method for entire cart
* No addon services required

**Common merchant types:**

* Apparel and accessories
* Books and media
* Small electronics
* Beauty products
* Standard-shipped items only

### Use Full Cart API When:

**Your checkout needs:**

* Mix of standard shipping and scheduled delivery
* Items requiring different fulfillment types
* Addon services (warranties, protection plans)
* In-store pickup options
* Complex shipping scenarios

**Common merchant types:**

* Furniture retailers (scheduled delivery)
* Large appliances (installation required)
* Mixed catalogs (standard + special delivery)
* Merchants offering warranties/protection

## Real-World Examples

### Example 1: Fashion Retailer

**Cart contains:** 3 shirts, 2 pants, 1 pair of shoes

**Simple Cart API** - Perfect fit

* All items ship the same way
* Standard parcel delivery
* Single shipping method selection

### Example 2: Furniture Store

**Cart contains:** Dining table + Throw pillows

**Simple Cart API** - Won't work
**Full Cart API** - Required

Why? The table needs scheduled delivery with time slot selection, while pillows ship standard. Full Cart API automatically creates two shipments.

### Example 3: Electronics Store

**Cart contains:** Laptop + Laptop bag

**Both APIs work!** Choose based on:

* Simple Cart API: If no warranties offered
* Full Cart API: If offering extended warranties or protection plans

## Feature Comparison

| Feature                    | Simple Cart API   | Full Cart API                |
| -------------------------- | ----------------- | ---------------------------- |
| **API Version**            | `/api/v1/`        | `/api/v2/`                   |
| **Response Structure**     | Flat cart         | Cart with shipments & addons |
| **Shipping Selection**     | One for all items | Per shipment                 |
| **Fulfillment Types**      | Standard only     | Standard, scheduled, pickup  |
| **Addons**                 | Not supported     | Three-tier system            |
| **Integration Complexity** | Low               | Medium                       |

## Response Structure Differences

### Simple Cart API Response

```json theme={null}
{
  "line_items": [
    { "sku": "SHIRT-001", "quantity": 2 },
    { "sku": "PANTS-001", "quantity": 1 }
  ],
  "shipping_method": {
    "description": "Standard Ground",
    "price": { "value": 9.99 }
  },
  "total": { "value": 109.99 }
}
```

### Full Cart API Response

```json theme={null}
{
  "line_items": [
    { "sku": "SHIRT-001", "quantity": 2 },
    { "sku": "PANTS-001", "quantity": 1 }
  ],
  "shipments": [
    {
      "shipment_id": "ship_001",
      "line_item_ids": ["item_001", "item_002"],
      "fulfillment_type": {
        "id": "SHIP_TO_ADDRESS",
        "name": "Ship to Address"
      },
      "shipping_method_options": [...]
    }
  ],
  "addons": {
    "offers": [...],
    "selections": []
  },
  "total": { "value": 109.99 }
}
```

## Migration Path

Starting with Simple Cart API and need to upgrade later?

**What stays the same:**

* Authentication method
* Merchant connections
* Basic operations
* Error handling

**What changes:**

* Response structure (adds shipments and addons)
* Endpoint versions (v1 → v2)
* Additional features available

## Decision Flowchart

```mermaid theme={null}
flowchart TD
    A[Start] --> B{Want fastest possible<br/>checkout experience?}
    B -->|Yes| C{Standard shipping only?}
    C -->|Yes| D[Use 1-Step Checkout]
    C -->|No| E{Do products need<br/>different shipping methods?}
    B -->|No| E
    E -->|Yes| F[Use Full Cart API]
    E -->|No| G{Need addon services?}
    G -->|Yes| F
    G -->|No| H{Need scheduled delivery?}
    H -->|Yes| F
    H -->|No| I[Use Simple Cart API]
```

## Recommendation

<Tabs>
  <Tab title="For Flexibility">
    **Use Simple Cart API** if you need:

    * Multi-step checkout control
    * Cart persistence
    * Basic promotional codes
    * Standard checkout flow

    Perfect for: Traditional e-commerce, multi-product catalogs
  </Tab>

  <Tab title="For Advanced Features">
    **Use Full Cart API** if you need:

    * Multiple fulfillment types
    * Addon services (warranties, gift wrap)
    * Complex shipping scenarios
    * B2B features

    Perfect for: Furniture stores, electronics retailers, B2B commerce
  </Tab>
</Tabs>

***

## Implementation Guides

Now that you understand the differences, choose your implementation path:

<CardGroup cols={3}>
  <Card title="1-Step Checkout" icon="bolt" href="/guides/one-step-checkout">
    Implement checkout in a single API call for maximum conversion
  </Card>

  <Card title="Simple Cart API" icon="shopping-cart" href="/guides/simple-cart-api-guide">
    Standard multi-step checkout with basic features
  </Card>

  <Card title="Full Cart API" icon="boxes" href="/guides/full-cart-api-guide">
    Advanced features for complex e-commerce requirements
  </Card>
</CardGroup>