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

# Changelog

> Track changes and updates to the Cart API

<Info>
  This changelog documents all releases, updates, and breaking changes to the Cart API.
</Info>

## Recent Updates

<Badge variant="success">Current Version</Badge>

**Released**: January 15, 2024

### Major Features

<AccordionGroup>
  <Accordion title="Multi-Shipment Support">
    **The flagship feature of v2** - Split cart items into multiple shipments with different fulfillment methods.

    * Group items by fulfillment type (standard shipping, scheduled delivery, in-store pickup)
    * Each shipment can have its own shipping method and delivery preferences
    * Automatic shipment consolidation based on fulfillment rules
    * Support for mixed carts (ship some items, pick up others)

    ```json theme={null}
    {
      "shipments": [
        {
          "shipment_id": "ship_001",
          "fulfillment_type": "SHIP_TO_ADDRESS",
          "line_item_ids": ["item_1", "item_2"]
        },
        {
          "shipment_id": "ship_002", 
          "fulfillment_type": "PICKUP_IN_STORE",
          "line_item_ids": ["item_3"]
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="Three-Tier Addon System">
    Flexible addon architecture supporting various business models:

    * **Cart-level addons**: Apply to entire order (e.g., shipping protection)
    * **Item-level addons**: Apply to specific products (e.g., warranties)
    * **Group-level addons**: Apply to item bundles (e.g., installation services)

    Features:

    * Dynamic pricing per item or flat rate
    * Hierarchical addon options with parent-child relationships
    * Constraint system for exclusive selections
    * Eligibility rules based on cart contents
  </Accordion>

  <Accordion title="Enhanced Fulfillment Options">
    New fulfillment types beyond standard shipping:

    * **Scheduled Delivery**: Customers choose specific date and time windows
    * **In-Store Pickup**: Select store location and pickup time
    * **White Glove Service**: Premium delivery with setup/installation

    Each fulfillment type includes:

    * Availability checking
    * Dynamic pricing
    * Location-based options
    * Time slot management
  </Accordion>

  <Accordion title="Improved Response Structure">
    Cleaner, more consistent API responses:

    * Standardized field naming (e.g., `tax_total` instead of `tax`)
    * Explicit `schema_version` field for version detection
    * Nested objects for better organization
    * Consistent error response format
    * Enhanced metadata support
  </Accordion>
</AccordionGroup>

### Breaking Changes from v1

<Warning>
  These changes require code updates when migrating from v1.
</Warning>

<Tabs>
  <Tab title="Field Changes">
    | v1 Field          | v2 Field                      | Description               |
    | ----------------- | ----------------------------- | ------------------------- |
    | `tax`             | `tax_total`                   | Renamed for consistency   |
    | `shipping_method` | `shipments[].shipping_method` | Moved to shipment level   |
    | -                 | `schema_version`              | New required field        |
    | -                 | `addon_total`                 | New field for addon costs |
    | -                 | `shipments`                   | New array structure       |
  </Tab>

  <Tab title="Endpoint Changes">
    | Operation    | v1 Endpoint                  | v2 Endpoint                            |
    | ------------ | ---------------------------- | -------------------------------------- |
    | Add Item     | `POST /cart/add-item`        | `POST /cart/line-items`                |
    | Update Item  | `POST /cart/update-item`     | `PUT /cart/line-items/{id}`            |
    | Remove Item  | `POST /cart/remove-item`     | `DELETE /cart/line-items/{id}`         |
    | Set Shipping | `POST /cart/shipping-method` | `POST /cart/shipments/shipping-method` |
  </Tab>

  <Tab title="Request Format">
    ### Add Line Item

    **v1 Format:**

    ```json theme={null}
    {
      "variant_id": "WS12-XS-Orange",
      "quantity": 2
    }
    ```

    **v2 Format:**

    ```json theme={null}
    {
      "add_to_cart_ref": {
        "variant_id": "WS12-XS-Orange"
      },
      "quantity": 2
    }
    ```

    ### Update Shipping

    **v1 Format:**

    ```json theme={null}
    {
      "shipping_method_id": "standard"
    }
    ```

    **v2 Format:**

    ```json theme={null}
    {
      "shipment_id": "ship_001",
      "shipping_method_id": "standard"
    }
    ```
  </Tab>
</Tabs>

### New Endpoints

<CardGroup cols={2}>
  <Card title="Fulfillment Management">
    * `POST /cart/shipments/fulfillment-type`
    * `POST /cart/shipments/availability`
    * `POST /cart/shipments/consolidate`
  </Card>

  <Card title="Addon Services">
    * `POST /cart/addons`
    * `DELETE /cart/addons/{addon_id}`
    * `GET /cart/addons/eligible`
  </Card>

  <Card title="Session Features">
    * `GET /session/active-carts`
    * `POST /session/transfer`
    * `GET /session/postal-code`
  </Card>

  <Card title="Order Management">
    * `POST /cart/persist-order`
    * `GET /orders/by-device`
  </Card>
</CardGroup>

### Improvements

* **Performance**: 30% faster response times through optimized queries
* **Reliability**: Enhanced error handling and retry logic
* **Security**: Improved authentication token validation
* **Compatibility**: Full backward compatibility mode available
* **Documentation**: Comprehensive API documentation with examples

### Bug Fixes

* Fixed race condition in concurrent cart updates
* Resolved timezone issues in scheduled delivery slots
* Fixed decimal precision errors in tax calculations
* Corrected inventory validation for bundle products
* Fixed promo code application order issues

### Migration Notes

<Steps>
  <Step title="Update Base URLs">
    Change all endpoints from `/api/v1/` to `/api/v2/`
  </Step>

  <Step title="Handle New Response Fields">
    Update response parsing to handle `shipments` array and `tax_total`
  </Step>

  <Step title="Test Backward Compatibility">
    V2 maintains single-shipment mode for v1-style requests
  </Step>

  <Step title="Adopt New Features Gradually">
    Start with basic v2, then implement multi-shipment and addons
  </Step>
</Steps>

## Version 1.5.0

<Badge variant="neutral">Previous Version</Badge>

**Released**: October 10, 2023

### Features

* Added promotional code support
* Introduced customer consent management
* Added email validation for checkout
* Support for gift messages

### Improvements

* Enhanced error messages with more context
* Improved cart persistence across sessions
* Better handling of out-of-stock scenarios

### Bug Fixes

* Fixed currency conversion rounding errors
* Resolved session timeout issues
* Fixed cart merge conflicts

## Version 1.4.0

**Released**: July 22, 2023

### Features

* International shipping support
* Multi-currency pricing
* Tax-inclusive pricing option
* Quantity-based discounts

### Improvements

* Faster cart calculations
* Better mobile SDK support
* Enhanced webhook reliability

## Roadmap

<Tip>
  These features are planned for future releases. Timelines are subject to change.
</Tip>

### Q2 2024 (v2.1)

* GraphQL API support
* Real-time inventory updates
* Advanced bundle configuration
* Subscription product support

### Q3 2024 (v2.2)

* B2B features (quotes, net terms)
* Multi-vendor marketplace support
* Advanced analytics endpoints
* Loyalty program integration

### Q4 2024 (v2.3)

* AI-powered product recommendations
* Voice commerce support
* Augmented reality previews
* Social commerce integration

## Deprecation Notices

<Warning>
  The following features will be deprecated in future versions:
</Warning>

### Planned for v2.2

* Legacy webhook format (use v2 webhooks)
* XML response format (JSON only)
* Basic auth support (use bearer tokens)

### Planned for v3.0

* Cart API v1 endpoints (full sunset)
* Legacy error codes
* Non-standard date formats

## Support Policy

| Version | Status        | Support Until      |
| ------- | ------------- | ------------------ |
| v2.0.x  | **Current**   | Active development |
| v1.5.x  | Maintenance   | December 2024      |
| v1.4.x  | Security only | June 2024          |
| \< v1.4 | End of life   | No support         |

## Stay Updated

<CardGroup cols={2}>
  <Card title="API Status" icon="chart-simple" href="https://status.firmly.work">
    Service status and incidents
  </Card>

  <Card title="Developer Newsletter" icon="envelope" href="https://firmly.com/newsletter">
    Monthly updates and tips
  </Card>
</CardGroup>

## Feedback

We value your input on the Cart API. Please share your feedback:

* **Feature Requests**: [feedback@firmly.com](mailto:feedback@firmly.com)
* **Bug Reports**: [GitHub Issues](https://github.com/firmly/cart-api/issues)
* **Community**: [Discord Server](https://discord.gg/firmly)