Changelog

This changelog documents all releases, updates, and breaking changes to the Cart API.

Recent Updates

Current Version Released: January 15, 2024

Major Features

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)

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

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

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

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

Breaking Changes from v1

These changes require code updates when migrating from v1.

Field Changes
Endpoint Changes
Request Format

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

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`

Add Line Item

v1 Format:

{
  "variant_id": "WS12-XS-Orange",
  "quantity": 2
}

v2 Format:

{
  "add_to_cart_ref": {
    "variant_id": "WS12-XS-Orange"
  },
  "quantity": 2
}

Update Shipping

v1 Format:

{
  "shipping_method_id": "standard"
}

v2 Format:

{
  "shipment_id": "ship_001",
  "shipping_method_id": "standard"
}

New Endpoints

Fulfillment Management

POST /cart/shipments/fulfillment-type
POST /cart/shipments/availability
POST /cart/shipments/consolidate

Addon Services

POST /cart/addons
DELETE /cart/addons/{addon_id}
GET /cart/addons/eligible

Session Features

GET /session/active-carts
POST /session/transfer
GET /session/postal-code

Order Management

POST /cart/persist-order
GET /orders/by-device

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

Update Base URLs

Change all endpoints from /api/v1/ to /api/v2/

Handle New Response Fields

Update response parsing to handle shipments array and tax_total

Test Backward Compatibility

V2 maintains single-shipment mode for v1-style requests

Adopt New Features Gradually

Start with basic v2, then implement multi-shipment and addons

Version 1.5.0

Previous Version 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

These features are planned for future releases. Timelines are subject to change.

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

The following features will be deprecated in future versions:

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

API Status

Service status and incidents

Developer Newsletter

Monthly updates and tips

Feedback

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

Feature Requests: feedback@firmly.com
Bug Reports: GitHub Issues
Community: Discord Server

Home

Core Concepts

Implementation Guides

Ask Agent SDK

API Reference

firmly Connect

Resources

Recent Updates

Major Features

Breaking Changes from v1

Add Line Item

Update Shipping

New Endpoints

Fulfillment Management

Addon Services

Session Features

Order Management

Improvements

Bug Fixes

Migration Notes

Version 1.5.0

Features

Improvements

Bug Fixes

Version 1.4.0

Features

Improvements

Roadmap

Q2 2024 (v2.1)

Q3 2024 (v2.2)

Q4 2024 (v2.3)

Deprecation Notices

Planned for v2.2

Planned for v3.0

Support Policy

Stay Updated

API Status

Developer Newsletter

Feedback

​Recent Updates

​Major Features

​Breaking Changes from v1

​Add Line Item

​Update Shipping

​New Endpoints

Fulfillment Management

Addon Services

Session Features

Order Management

​Improvements

​Bug Fixes

​Migration Notes

​Version 1.5.0

​Features

​Improvements

​Bug Fixes

​Version 1.4.0

​Features

​Improvements

​Roadmap

​Q2 2024 (v2.1)

​Q3 2024 (v2.2)

​Q4 2024 (v2.3)

​Deprecation Notices

​Planned for v2.2

​Planned for v3.0

​Support Policy

​Stay Updated

API Status

Developer Newsletter

​Feedback

Recent Updates

Major Features

Breaking Changes from v1

Add Line Item

Update Shipping

New Endpoints

Improvements

Bug Fixes

Migration Notes

Version 1.5.0

Features

Improvements

Bug Fixes

Version 1.4.0

Features

Improvements

Roadmap

Q2 2024 (v2.1)

Q3 2024 (v2.2)

Q4 2024 (v2.3)

Deprecation Notices

Planned for v2.2

Planned for v3.0

Support Policy

Stay Updated

Feedback