Carts
Overview
The Cart object is the central entity in Violet's unified checkout API that represents a shopping cart containing products from one or more merchants. It serves as the primary container for managing multi-merchant checkout flows and automatically organizes items into "bags" based on the merchant they come from.
Key Concepts
Cart vs Order
Cart: Active shopping session that can be modified (add/remove items, apply discounts, set shipping)
Order: Immutable record created after cart submission to merchants' platforms
Multi-Merchant Architecture
A single cart can contain products from multiple merchants
Items are automatically organized into bags - one bag per merchant
Each bag mirrors the cart/order structure of the merchant's ecommerce platform
Core Properties
Identification
{
"id": 10000, // Unique cart ID in Violet
"token": "fz8x7gksdjsy2p9...", // Cart token for secure access
"app_order_id": "order_123", // Your system's order identifier
"external_id": "ref_456" // Optional reference ID
}
Ownership & Context
{
"user_id": 10002, // User who created the cart
"app_id": 10001, // Your application ID
"developer_id": 10001, // Developer account ID
"app_name": "Your App Name" // Name of originating application
}
Financial Summary
All monetary values are in cents in the base currency:
{
"base_currency": "USD", // Cart currency (set at creation)
"sub_total": 2500, // Item prices before discounts/shipping/tax
"shipping_total": 599, // Total shipping costs
"tax_total": 200, // Total tax amount
"discount_total": 500, // Total discount amount
"total": 2799, // Final total (sub_total + shipping + tax - discounts)
"taxes_included": false // Whether taxes are included in item prices
}
Bags Structure
Each cart contains an array of bags - one per merchant:
{
"bags": [
{
"id": 11111, // Unique bag ID
"merchant_id": 10000, // Merchant this bag belongs to
"status": "IN_PROGRESS", // Bag status (see lifecycle below)
"fulfillment_status": "PROCESSING",
"financial_status": "UNPAID",
"platform": "SHOPIFY", // Merchant's ecommerce platform
"commission_rate": 0.15, // Your commission rate (15%)
"external_checkout": true, // Whether bag has external cart representation
// Financial totals for this bag
"sub_total": 2500,
"shipping_total": 599,
"tax_total": 200,
"discount_total": 500,
"total": 2799,
// Items in this bag
"skus": [...], // Array of SKU objects
"shipping_method": {...}, // Applied shipping method
"discounts": [...], // Applied discount codes
"taxes": [...] // Tax breakdown
}
]
}
Bag Lifecycle States
IN_PROGRESS
: Cart is being built, can be modifiedSUBMITTED
: Cart has been sent to merchant platformACCEPTED
: Merchant platform confirmed the orderCOMPLETED
: All items fulfilled and shippedREFUNDED
: All items returned and refunded
SKU (Product Items) Structure
Each bag contains SKUs representing individual products:
{
"skus": [
{
"id": 10000, // Violet SKU ID
"sku_id": 99999, // Merchant's SKU ID
"external_id": "1234567890", // SKU ID in merchant's system
"name": "Nintendo Entertainment System",
"brand": "Nintendo",
"thumbnail": "https://res.cloudinary.com/...",
"quantity": 2, // Quantity in cart
"price": 9999, // Price per unit (in cents)
"line_price": 19998, // Total for this line (price × quantity)
"weight": 1.0, // Item weight
"available": true, // Still available for purchase
"status": "IN_PROGRESS", // Current status
"product_type": "PHYSICAL", // PHYSICAL or DIGITAL
"custom": false // Whether price was overridden
}
]
}
Customer Information
{
"customer": {
"user_id": 10000,
"first_name": "Super",
"last_name": "Mario",
"email": "[email protected]",
"name": "Super Mario",
"shipping_address": {
"address_1": "123 Main St",
"city": "New York",
"state": "NY",
"postal_code": "10001",
"country": "US",
"type": "SHIPPING"
},
"billing_address": {...}, // Similar structure
"same_address": true // Whether billing = shipping
}
}
Payment Integration
Standard Payment Flow
{
"payment_transactions": [
{
"id": 84808,
"payment_provider": "STRIPE",
"amount": 900,
"currency": "USD",
"capture_status": "REQUIRES_PAYMENT_METHOD",
"capture_method": "AUTOMATIC",
"status": "REQUIRES_PAYMENT_METHOD"
}
]
}
Wallet-Based Checkout (Apple Pay, Google Pay)
{
"wallet_based_checkout": true,
"stripe_key": "pk_test_UHg8oLvg4rrDCbvtqfwTE8qd",
"payment_intent_client_secret": "pi_3MbFHUK29KDiBVld0N8b8EDd_secret_..."
}
Error Handling
Carts include comprehensive error tracking:
{
"errors": [
{
"id": "error_123",
"entity_type": "SKU", // What caused the error
"entity_id": "sku_456", // ID of problematic entity
"message": "Item out of stock",
"resolved": false,
"date_created": "2024-06-17T10:30:00Z",
"date_resolved": null
}
]
}
Important: Always check the errors
array - the API returns 200 even with bag-level errors.
Special Features
Multi-Currency Support
Set currency at cart creation with
base_currency
parameterOnce a cart has been created in a currency, you cannot change it. You will need to create a new cart with the updated base_currency to achieve this.
Real-time exchange rates applied automatically or using presentment currencies
Discount Codes
Discount codes can be added during cart creation ([POST]/checkout/cart) or through an exclusive endpoint ([POST]/checkout/cart/:cart_id/discounts)
Validated against each merchant's platform
States:
PENDING
,APPLIED
,INVALID
,EXPIRED
,ERROR
See Discounts section for more info
Shipping Methods
Automatically retrieved from each merchant's platform
Applied per bag (per merchant)
Calculated based on shipping address and item weights
Key API Endpoints
Create cart
/checkout/cart
POST
Get cart
/checkout/cart/{id}
GET
Get by token
/checkout/cart/byToken/{token}
GET
Delete cart
/checkout/cart/{id}
DELETE
Add items
/checkout/cart/{id}/items
POST
Apply payment
/checkout/cart/{id}/payment
POST
Set shipping
/checkout/cart/{id}/shipping
POST
Add discounts
/checkout/cart/{id}/discounts
POST
Submit cart
/checkout/cart/{id}/submit
POST
Best Practices
Cart Management
Use app_order_id: While not enforced unique in Violet's system, it is strongly recommended that unique values are used for each cart to help correlate identifiers between Violet's system and yours.
Error Checking: Always examine the
errors
array after any cart operationCurrency Immutability: Choose currency carefully at creation - it cannot be changed later
Bag Awareness: Remember that multi-merchant carts create multiple bags, each potentially with different shipping methods, discounts, and states
Performance Considerations
Carts persist indefinitely - implement cleanup for abandoned carts
Carts with wallet_based_checkout set to true cannot be completed without completing the front end client work listed below, specifically the Stripe Element integration and the client side Payment Confirmation. There is no API-only path complete such an order
Security
Use cart tokens for client-side access instead of cart IDs
Validate cart ownership before allowing modifications
Implement proper authentication for cart operations
Example: Basic Cart Creation
// Create a cart with items from multiple merchants
const cart = await fetch('/v1/checkout/cart', {
method: 'POST',
headers: {
'X-Violet-Token': authToken,
'Content-Type': 'application/json'
},
body: JSON.stringify({
base_currency: 'USD',
app_order_id: 'your-order-123',
skus: [
{
sku_id: 12345, // From Merchant A
quantity: 2
},
{
sku_id: 67890, // From Merchant B
quantity: 1
}
]
})
});
const cartData = await cart.json();
// cartData.bags will contain 2 bags (one per merchant)
// Each bag will have the respective SKUs
This cart object design enables Violet's core value proposition: unified multi-merchant checkout through a single API interface, while maintaining the flexibility and features of individual ecommerce platforms.
Last updated
Was this helpful?