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

# How Firmly Works

> Understand the core architecture and flow of the Firmly Cart API

The Firmly Cart API provides a unified interface for cart management across different e-commerce platforms.

## Core Concept

<Info>
  Firmly acts as a standardization layer between your application and merchant systems, providing consistent cart operations regardless of the underlying platform.
</Info>

### What Firmly Provides

1. **Unified API**: Same endpoints work across all merchant platforms
2. **Standardized Responses**: Consistent data format regardless of merchant
3. **Device Authentication**: Secure, session-based access control
4. **Real-time Operations**: Direct integration with merchant systems

## Authentication Flow

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant Firmly API
    
    Client->>Firmly API: POST /api/v1/browser-session<br/>x-firmly-app-id: YOUR_APP_ID
    Firmly API-->>Client: { access_token: "..." }
    
    Client->>Firmly API: GET /api/v2/domains/{domain}/cart<br/>x-firmly-authorization: access_token
    Firmly API-->>Client: Standardized cart response
```

## Cart States

Carts have dynamically determined states based on their current condition:

* **active**: Default state, all operations allowed
* **submitted**: Order completed (has platform\_order\_number)
* **item\_not\_shippable**: Items cannot ship to selected address
* **checkout\_blocked**: Has errors preventing checkout

## Key Identifiers

Every response includes:

* **platform\_id**: The e-commerce platform type
* **shop\_id**: The specific merchant domain
* **cart\_id**: Unique cart identifier

## Next Steps

* [Authentication](/api-reference/authentication/browser-session) - Set up API access
* [Cart Lifecycle](/concepts/cart-lifecycle) - Detailed state management
* [Implementation Guides](/guides/choosing-your-api) - Build your first integration