Skip to main content

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

Firmly offers two API options to match different integration needs. Both connect to the same merchant systems - the difference is in complexity and capabilities.
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.

​
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

FeatureSimple Cart APIFull Cart API
API Version/api/v1//api/v2/
Response StructureFlat cartCart with shipments & addons
Shipping SelectionOne for all itemsPer shipment
Fulfillment TypesStandard onlyStandard, scheduled, pickup
AddonsNot supportedThree-tier system
Integration ComplexityLowMedium

​
Response Structure Differences

​
Simple Cart API Response

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

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

​
Recommendation

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

​
Implementation Guides

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

1-Step Checkout

Implement checkout in a single API call for maximum conversion

Simple Cart API

Standard multi-step checkout with basic features

Full Cart API

Advanced features for complex e-commerce requirements