Full Cart API Guide
Build a complete checkout flow with Firmly’s Full Cart API. This guide walks through adding items, setting shipping, and completing payment.When to Use Full Cart API
The Full Cart API supports complex fulfillment scenarios like split shipments and scheduled delivery. Use it when you need:- Mix of standard shipping and scheduled delivery
- Items requiring different fulfillment types
- Addon services (warranties, protection plans)
- In-store pickup options
- Complex shipping scenarios
Prerequisites
Before starting, ensure you have:Firmly Application ID
Your Application ID from Firmly (contact support if you don’t have one)
Test Merchant Domain
Work with Firmly to enable your app ID for a specific test store
API Client
cURL, Postman, or your preferred HTTP client
Important: Before you can access a merchant’s store, Firmly must configure your app ID to work with that specific domain. Contact our team to set up access to your test merchant.
Step 1: Authenticate
Get an access token for your session:access_token from the response as x-firmly-authorization in all API calls.
Step 2: Browse Products
Discover available products from the merchant:Step 3: Add to Cart
Add a product variant to the cart:Step 4: Set Shipping Address
Add shipping information and get available shipping methods:Step 5: Select Shipping Method
Choose a shipping method for each shipment:Step 6: Complete the Order
Get the public key and complete the order with encrypted payment:Complete Example
Key Differences from Simple Cart API
| Feature | Simple Cart API | Full Cart API |
|---|---|---|
| Cart Structure | Flat | Shipment-based |
| Shipping | One method for all | Per-shipment selection |
| Fulfillment | Standard only | Multiple types |
| Addons | Not supported | Full support |
Error Handling
Common errors and their meanings:ErrorCartNotFound- Cart session expiredErrorProductNotFound- Invalid variant IDErrorNotEnoughStock- Item out of stockErrorCountryNotSupported- Shipping country not availableCreditCardDeclined- Payment failed
Next Steps
- Review Error Codes for comprehensive error handling
- Explore Addon Management for warranties and services
- Check Session Management for managing multiple carts