Build E-Commerce Shopping Carts

{
  "shoppingCartConfig": {
    "basicSettings": {
      "useShoppingCartFeature": true,
      "cartObjectName": "cart",
      "currency": "USD"
    }
  }
}

{
  "basicSettings": {
    "useShoppingCartFeature": true,
    "cartObjectName": "cart",
    "currency": "USD",
    "requireLogin": true,
    "guestCartEnabled": false,
    "supportNotes": true,
    "supportMetadata": true,
    "cartStatusValues": ["active", "abandoned", "checkedOut", "convertedToOrder"]
  }
}

{
  "pricingSettings": {
    "catalogPricesIncludeVat": false,
    "defaultVatRate": 0.20,
    "roundingStrategy": "perLine",
    "roundingPrecision": 2,
    
    "discountSettings": {
      "supportType": "bothLevels",
      "allocationMode": "proportional"
    },
    
    "shipmentSettings": {
      "enabled": true,
      "defaultShipmentVatRate": 0.20
    },
    
    "extraChargeSettings": {
      "enabled": false,
      "storeBreakdown": true
    }
  }
}

{
  "itemSettings": {
    "itemObjectSuffix": "Item",
    "supportCategory": true,
    "supportBrand": true,
    "supportProductGroup": true,
    "supportVendor": false,
    "supportGiftItems": true,
    "supportItemMetadata": false
  }
}

{
  "loyaltySettings": {
    "enabled": true,
    "supportPointsEarning": true,
    "supportPointsRedemption": true,
    "pointsToMoneyRate": 100
  }
}

{
  "logisticsSettings": {
    "enabled": true,
    "trackWeight": true,
    "trackDimensions": true,
    "calculateDimensionalWeight": true,
    "dimFactor": 5000
  }
}

{
  "promotionSettings": {
    "staticPromotions": {
      "freeShippingThreshold": {
        "enabled": true,
        "minCartTotal": 100,
        "customerMessage": "Free shipping on orders over $100!"
      },
      
      "cartTotalDiscount": {
        "enabled": true,
        "tiers": [
          { "minCartTotal": 100, "discountPercent": 5 },
          { "minCartTotal": 250, "discountPercent": 10 },
          { "minCartTotal": 500, "discountPercent": 15 }
        ],
        "maxDiscountAmount": 200
      },
      
      "membershipDiscounts": {
        "enabled": true,
        "membershipProperty": "membershipLevel",
        "levels": [
          { "membershipLevel": "silver", "discountPercent": 5 },
          { "membershipLevel": "gold", "discountPercent": 10 },
          { "membershipLevel": "platinum", "discountPercent": 15 }
        ]
      }
    },
    
    "dynamicPromotionsEnabled": true,
    "couponsEnabled": true,
    "supportMultipleCoupons": false,
    "maxCouponsPerCart": 1,
    
    "campaignSettings": {
      "supportBudgetLimits": true,
      "supportUsageLimits": true,
      "supportCustomerLimits": true,
      "supportScheduling": true
    }
  }
}

{
  "redisSettings": {
    "keyPrefix": "cart:",
    "cartTtlSeconds": 86400,
    "persistStrategy": "onEveryChange"
  }
}

{
  "apiSettings": {
    "routePrefix": "/cart",
    "grpcEnabled": false
  }
}

const response = await fetch(`${serviceUrl}/cart`, {
  method: "GET",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${accessToken}`
  }
});

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "userId": "user-123",
  "status": "active",
  "currency": "USD",
  "itemCount": 3,
  "totalQuantity": 5,
  "subtotal": 299.97,
  "discountTotal": 29.99,
  "vatTotal": 53.99,
  "grandTotal": 323.97,
  "items": [
    {
      "id": "item-1",
      "barcode": "SKU-001",
      "productName": "Wireless Headphones",
      "quantity": 2,
      "unitPrice": 99.99,
      "lineTotal": 199.98
    },
    {
      "id": "item-2",
      "barcode": "SKU-002",
      "productName": "Phone Case",
      "quantity": 3,
      "unitPrice": 33.33,
      "lineTotal": 99.99
    }
  ],
  "appliedCampaignIds": ["campaign-summer-2024"],
  "couponCode": "SAVE10"
}

const response = await fetch(`${serviceUrl}/cart/items`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${accessToken}`
  },
  body: JSON.stringify({
    barcode: "SKU-001",
    quantity: 2,
    productName: "Wireless Headphones",
    unitPrice: 99.99
  })
});

const response = await fetch(`${serviceUrl}/cart/items/SKU-001`, {
  method: "PUT",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${accessToken}`
  },
  body: JSON.stringify({
    quantity: 5
  })
});

await fetch(`${serviceUrl}/cart/items/SKU-001`, {
  method: "DELETE",
  headers: {
    "Authorization": `Bearer ${accessToken}`
  }
});

await fetch(`${serviceUrl}/cart/items`, {
  method: "DELETE",
  headers: {
    "Authorization": `Bearer ${accessToken}`
  }
});

const response = await fetch(`${serviceUrl}/cart/coupons`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${accessToken}`
  },
  body: JSON.stringify({
    couponCode: "SUMMER20"
  })
});

{
  "success": true,
  "couponCode": "SUMMER20",
  "discountAmount": 50.00,
  "message": "Coupon applied successfully! You saved $50.00",
  "cart": { /* updated cart object */ }
}

{
  "success": false,
  "error": "COUPON_EXPIRED",
  "message": "This coupon has expired"
}

await fetch(`${serviceUrl}/cart/coupons/SUMMER20`, {
  method: "DELETE",
  headers: {
    "Authorization": `Bearer ${accessToken}`
  }
});

const response = await fetch(`${serviceUrl}/v1/checkoutcart/${cartId}`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${accessToken}`
  },
  body: JSON.stringify({
    shippingAddress: {
      street: "123 Main St",
      city: "New York",
      state: "NY",
      postalCode: "10001",
      country: "US"
    },
    billingAddress: {
      street: "123 Main St",
      city: "New York",
      state: "NY",
      postalCode: "10001",
      country: "US"
    },
    paymentMethod: "pm_card_visa",
    notes: "Please leave at door"
  })
});

{
  "status": "OK",
  "statusCode": "200",
  "sys_cart": {
    "id": "cart-123",
    "status": "checkedOut",
    "checkedOutAt": "2024-01-15T10:30:00Z",
    "grandTotal": 323.97
  },
  "checkoutResult": {
    "success": true,
    "orderId": "order-456",
    "orderNumber": "ORD-2024-0001",
    "totalAmount": 323.97,
    "itemsCount": 5,
    "promotionsApplied": ["SUMMER20"],
    "pointsEarned": 324
  }
}

const response = await fetch(`${serviceUrl}/v1/createcartcampaign`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${adminToken}`
  },
  body: JSON.stringify({
    name: "Summer Sale 2024",
    code: "SUMMER2024",
    description: "20% off all summer items",
    startDate: "2024-06-01T00:00:00Z",
    endDate: "2024-08-31T23:59:59Z",
    priority: 10,
    isStackable: false,
    rules: {
      type: "cartTotal",
      minCartTotal: 50
    },
    reward: {
      type: "percentageDiscount",
      value: 20,
      maxAmount: 100
    },
    usageLimitTotal: 10000,
    usageLimitPerCustomer: 1,
    budgetLimit: 50000
  })
});

const response = await fetch(
  `${serviceUrl}/cartcoupons/validate?code=SUMMER20&cartTotal=150`,
  {
    method: "GET",
    headers: {
      "Authorization": `Bearer ${accessToken}`
    }
  }
);

{
  "isValid": true,
  "message": "Coupon is valid! You'll save $30.00",
  "discount": {
    "type": "percentage",
    "value": 20,
    "calculatedAmount": 30.00
  },
  "coupon": {
    "code": "SUMMER20",
    "campaignId": "campaign-123",
    "endDate": "2024-08-31T23:59:59Z",
    "remainingUses": 4999
  }
}

// In your service library
async function validateItemBeforeAdd(context) {
  const { cart, item, session, services } = context;
  
  // Check if item is available in user's region
  const regionCheck = await services.productService.checkRegionAvailability(
    item.productId,
    session.region
  );
  
  if (!regionCheck.available) {
    throw new CartEventError(
      'ITEM_NOT_AVAILABLE',
      'This item is not available in your region'
    );
  }
  
  // Modify the item if needed
  return {
    item: {
      ...item,
      regionPrice: regionCheck.regionalPrice
    }
  };
}

async function calculateShippingByZone(context) {
  const { cart, session, services } = context;
  
  const shippingZone = await services.shippingService.getZone(
    session.shippingAddress.postalCode
  );
  
  const shippingCost = calculateZonedShipping(
    cart.totalWeight,
    shippingZone
  );
  
  return {
    shipping: {
      cost: shippingCost,
      vatRate: 0.20,
      method: shippingZone.defaultMethod
    }
  };
}

{
  "eventSettings": {
    "itemEvents": {
      "onBeforeAddItem": "validateItemBeforeAdd"
    },
    "pricingEvents": {
      "onCalculateShipping": "calculateShippingByZone"
    }
  }
}

{
  "shoppingCartConfig": {
    "basicSettings": {
      "useShoppingCartFeature": true,
      "cartObjectName": "cart",
      "currency": "USD",
      "requireLogin": false,
      "guestCartEnabled": true
    },
    "pricingSettings": {
      "defaultVatRate": 0.08,
      "discountSettings": {
        "supportType": "cartLevel"
      },
      "shipmentSettings": {
        "enabled": true
      }
    },
    "promotionSettings": {
      "staticPromotions": {
        "freeShippingThreshold": {
          "enabled": true,
          "minCartTotal": 50,
          "customerMessage": "Free shipping on orders over $50!"
        }
      }
    }
  }
}

{
  "shoppingCartConfig": {
    "basicSettings": {
      "useShoppingCartFeature": true,
      "cartObjectName": "subscriptionCart",
      "currency": "USD",
      "requireLogin": true
    },
    "loyaltySettings": {
      "enabled": true,
      "supportPointsEarning": true,
      "supportPointsRedemption": true,
      "pointsToMoneyRate": 100
    },
    "promotionSettings": {
      "staticPromotions": {
        "membershipDiscounts": {
          "enabled": true,
          "membershipProperty": "subscriptionTier",
          "levels": [
            { "membershipLevel": "basic", "discountPercent": 5 },
            { "membershipLevel": "premium", "discountPercent": 15 },
            { "membershipLevel": "vip", "discountPercent": 25 }
          ]
        }
      }
    }
  }
}

{
  "shoppingCartConfig": {
    "basicSettings": {
      "useShoppingCartFeature": true,
      "cartObjectName": "marketplaceCart",
      "currency": "USD"
    },
    "itemSettings": {
      "supportVendor": true,
      "supportCategory": true,
      "supportBrand": true
    },
    "promotionSettings": {
      "staticPromotions": {
        "cartTotalDiscount": {
          "enabled": true,
          "tiers": [
            { "minCartTotal": 100, "discountPercent": 5 },
            { "minCartTotal": 250, "discountPercent": 10 },
            { "minCartTotal": 500, "discountPercent": 15 }
          ]
        }
      },
      "dynamicPromotionsEnabled": true,
      "couponsEnabled": true,
      "campaignSettings": {
        "supportBudgetLimits": true,
        "supportUsageLimits": true,
        "supportScheduling": true
      }
    }
  }
}

{
  "shoppingCartConfig": {
    "basicSettings": {
      "useShoppingCartFeature": true,
      "cartObjectName": "wholesaleCart",
      "currency": "USD",
      "requireLogin": true
    },
    "pricingSettings": {
      "catalogPricesIncludeVat": false,
      "defaultVatRate": 0,
      "shipmentSettings": {
        "enabled": true
      }
    },
    "logisticsSettings": {
      "enabled": true,
      "trackWeight": true,
      "trackDimensions": true,
      "calculateDimensionalWeight": true,
      "dimFactor": 5000
    },
    "eventSettings": {
      "pricingEvents": {
        "onCalculateShipping": "calculateFreightShipping",
        "onCalculateVAT": "handleB2BTaxExemption"
      }
    }
  }
}

{
  "shoppingCartConfig": {
    "basicSettings": {
      "useShoppingCartFeature": true,
      "cartObjectName": "flashCart",
      "currency": "USD"
    },
    "redisSettings": {
      "keyPrefix": "flash:",
      "cartTtlSeconds": 900,
      "persistStrategy": "onCheckout"
    },
    "promotionSettings": {
      "dynamicPromotionsEnabled": true,
      "couponsEnabled": true,
      "campaignSettings": {
        "supportScheduling": true,
        "supportUsageLimits": true,
        "supportDailyLimits": true
      }
    },
    "eventSettings": {
      "itemEvents": {
        "onBeforeAddItem": "reserveFlashInventory",
        "onStockValidation": "checkFlashStock"
      },
      "lifecycleEvents": {
        "onCartExpire": "releaseFlashReservation"
      }
    }
  }
}

// Cart service/store
class CartService {
  constructor(apiBaseUrl) {
    this.apiBaseUrl = apiBaseUrl;
  }

  async getCart() {
    const response = await fetch(`${this.apiBaseUrl}/cart`, {
      headers: this.getAuthHeaders()
    });
    return response.json();
  }

  async addItem(barcode, quantity, metadata = {}) {
    const response = await fetch(`${this.apiBaseUrl}/cart/items`, {
      method: 'POST',
      headers: {
        ...this.getAuthHeaders(),
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ barcode, quantity, ...metadata })
    });
    return response.json();
  }

  async updateItemQuantity(barcode, quantity) {
    const response = await fetch(`${this.apiBaseUrl}/cart/items/${barcode}`, {
      method: 'PUT',
      headers: {
        ...this.getAuthHeaders(),
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ quantity })
    });
    return response.json();
  }

  async removeItem(barcode) {
    await fetch(`${this.apiBaseUrl}/cart/items/${barcode}`, {
      method: 'DELETE',
      headers: this.getAuthHeaders()
    });
    return this.getCart();
  }

  async applyCoupon(couponCode) {
    const response = await fetch(`${this.apiBaseUrl}/cart/coupons`, {
      method: 'POST',
      headers: {
        ...this.getAuthHeaders(),
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ couponCode })
    });
    return response.json();
  }

  async removeCoupon(couponCode) {
    await fetch(`${this.apiBaseUrl}/cart/coupons/${couponCode}`, {
      method: 'DELETE',
      headers: this.getAuthHeaders()
    });
    return this.getCart();
  }

  async checkout(checkoutData) {
    const cart = await this.getCart();
    const response = await fetch(
      `${this.apiBaseUrl}/v1/checkoutcart/${cart.id}`,
      {
        method: 'POST',
        headers: {
          ...this.getAuthHeaders(),
          'Content-Type': 'application/json'
        },
        body: JSON.stringify(checkoutData)
      }
    );
    return response.json();
  }

  getAuthHeaders() {
    const token = localStorage.getItem('accessToken');
    return token ? { 'Authorization': `Bearer ${token}` } : {};
  }
}

// Generate or retrieve session ID for guest users
function getGuestSessionId() {
  let sessionId = localStorage.getItem('guestSessionId');
  if (!sessionId) {
    sessionId = crypto.randomUUID();
    localStorage.setItem('guestSessionId', sessionId);
  }
  return sessionId;
}

// Include session ID in requests for guest users
async function getCartForGuest() {
  const sessionId = getGuestSessionId();
  const response = await fetch(`${apiBaseUrl}/cart`, {
    headers: {
      'X-Session-Id': sessionId
    }
  });
  return response.json();
}

// Merge guest cart after login
async function mergeGuestCart(accessToken) {
  const sessionId = localStorage.getItem('guestSessionId');
  if (sessionId) {
    await fetch(`${apiBaseUrl}/cart/merge`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ sessionId })
    });
    localStorage.removeItem('guestSessionId');
  }
}

// WebSocket connection for real-time updates
const ws = new WebSocket(`wss://${serviceUrl}/ws`);

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  
  switch (message.type) {
    case 'cart.updated':
      // Refresh cart display
      updateCartUI(message.cart);
      break;
    case 'promotion.applied':
      // Show promotion notification
      showNotification(`Promotion applied: ${message.promotion.name}`);
      break;
    case 'item.outOfStock':
      // Alert user about stock issue
      showAlert(`${message.item.productName} is now out of stock`);
      break;
  }
};

async function completeCheckoutWithPayment(checkoutData, paymentMethodId) {
  // Step 1: Checkout the cart (cart → order)
  const checkoutResponse = await fetch(
    `${serviceUrl}/v1/checkoutcart/${cartId}`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(checkoutData)
    }
  );
  
  const { checkoutResult } = await checkoutResponse.json();
  
  if (!checkoutResult.success) {
    throw new Error(checkoutResult.message);
  }
  
  // Step 2: Start payment for the order (order → charge)
  const paymentResponse = await fetch(
    `${serviceUrl}/v1/startorderpayment/${checkoutResult.orderId}`,
    {
      method: 'PATCH',
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        paymentUserParams: {
          paymentMethodId,
          return_url: `${window.location.origin}/payment-result`
        }
      })
    }
  );
  
  const { paymentResult } = await paymentResponse.json();
  
  // Step 3: Handle payment result
  if (paymentResult.paymentIntentInfo.status === 'succeeded') {
    // Payment complete - show success
    navigateToOrderConfirmation(checkoutResult.orderId);
  } else if (paymentResult.paymentIntentInfo.status === 'requires_action') {
    // 3D Secure required
    await handleStripe3DSecure(paymentResult.paymentIntentInfo);
  } else {
    // Payment failed
    showPaymentError(paymentResult);
  }
}

{
  "objectSettings": {
    "stripeOrder": {
      "objectIsAnOrderObject": true,
      "configuration": {
        "orderName": "CartOrder",
        "orderId": "this.order.id",
        "amount": "this.order.grandTotal",
        "currency": "this.order.currency",
        "description": "`Order #${this.order.orderNumber} - ${this.order.itemCount} items`",
        "orderStatusProperty": "status",
        "orderStatusUpdateDateProperty": "statusUpdatedAt",
        "orderOwnerIdProperty": "userId",
        "mapPaymentResultToOrderStatus": {
          "paymentResultStarted": ""paymentPending"",
          "paymentResultCanceled": ""paymentFailed"",
          "paymentResultFailed": ""paymentFailed"",
          "paymentResultSuccess": ""paid""
        }
      }
    }
  }
}

For each line item:
┌──────────────────────────────────────────────────────────────┐
│  unitPriceExVat                        (base price)          │
│       │                                                       │
│       ▼                                                       │
│  - itemDiscountAmount                  (item-level discount) │
│       │                                                       │
│       ▼                                                       │
│  - cartDiscountAllocated               (allocated cart discount) │
│       │                                                       │
│       ▼                                                       │
│  = netUnitPriceExVat                   (final unit price)    │
│       │                                                       │
│       ├──────────────────────────────────────────────────────│
│       │                                  │                    │
│       ▼                                  ▼                    │
│  × quantity                          × vatRate               │
│       │                                  │                    │
│       ▼                                  ▼                    │
│  = lineTotalExVat                   = lineVatAmount          │
│       │                                  │                    │
│       └──────────────┬───────────────────┘                    │
│                      │                                        │
│                      ▼                                        │
│              = lineTotalIncVat                                │
└──────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────┐
│  Σ lineTotalExVat                   → subtotal               │
│                                                               │
│  subtotal - discountTotal           → discountedSubtotal     │
│                                                               │
│  discountedSubtotal + shipmentCost + extraCharges → totalExVat │
│                                                               │
│  Σ lineVatAmount + shipmentVat + extraChargesVat → totalVat  │
│                                                               │
│  totalExVat + totalVat              → grandTotal             │
└──────────────────────────────────────────────────────────────┘