API Reference
Complete guide to building shopping cart experiences with the Omnium Cart API. Learn how to create carts, manage line items, apply discounts, and complete checkout in headless e-commerce scenarios.
The Cart API enables you to build complete shopping cart experiences for headless e-commerce, point-of-sale systems, and custom checkout flows. This guide focuses on the most common workflows for integrating with Omnium.
Overview
A cart in Omnium represents a shopping session that can be converted into an order. Carts support:
- Line items with automatic price calculation and promotions
- Multiple shipping methods and split shipments
- Various payment methods including split payments
- Customer association and customer-specific pricing
- Validation before order creation
- Gift cards and coupon codes
Architecture
Base URL
All Cart API endpoints are available at:
Full API reference: Omnium Cart API Documentation
Cart model
The cart object contains all information about a shopping session. It inherits from the Order model with additional cart-specific properties.
Cart properties
| Property | Type | Description |
|---|---|---|
| Id | string | Unique cart identifier (e.g., "C12345") |
| Session | string | Session code for linking to a web session |
| ExpiredDate | DateTime? | When the cart expires and should no longer be shown to the customer |
| IsReadOnly | bool | If true, the cart cannot be modified |
| MarketId | string | Market identifier (affects pricing, currency, shipping options) |
| StoreId | string | Store identifier (affects inventory, pricing) |
| CustomerId | string | Associated customer ID |
| BillingCurrency | string | Currency code (e.g., "NOK", "SEK", "EUR") |
| OrderForm | OrderForm | Contains line items, shipments, payments, and totals |
| Status | string | Cart status (typically "Draft") |
OrderForm structure
| Property | Type | Description |
|---|---|---|
| LineItems | List<OrderLine> | Products in the cart |
| Shipments | List<Shipment> | Shipping selections |
| Payments | List<Payment> | Payment transactions |
| Discounts | List<Discount> | Applied discounts |
| SubTotal | decimal | Sum of line items before discounts |
| ShippingTotal | decimal | Total shipping cost |
| TaxTotal | decimal | Total tax amount |
| Total | decimal | Final total including tax |
| DiscountTotal | decimal | Total discount amount |
OrderLine structure
| Property | Type | Description |
|---|---|---|
| LineItemId | string | Unique line item identifier (GUID) |
| Code | string | Product SKU |
| DisplayName | string | Product name |
| Quantity | decimal | Quantity ordered |
| PlacedPrice | decimal | Unit price |
| ExtendedPrice | decimal | Total price (quantity × unit price) |
| LineItemDiscountAmount | decimal | Discount applied to this line |
| IsBundle | bool | True if this is a bundle product |
| Components | List<ProductComponent> | Bundle components (if applicable) |
Checkout flow
The typical headless e-commerce checkout follows this flow:
Step 1: Create a cart
Create a new cart by adding the first item. When you call AddItemToCart without a cartId, a new cart is created automatically.
Endpoint: POST /api/Cart/AddItemToCart
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| skuId | string | Yes | Product SKU identifier |
| quantity | decimal | No | Quantity to add (default: 1) |
| marketId | string | No | Market ID for pricing/currency |
| storeId | string | No | Store ID for inventory |
| customerId | string | No | Customer ID for personalized pricing |
Example request:
Example response:
Save the id from the response - you'll need it for all subsequent cart operations.
Step 2: Build the cart
Add more items
Endpoint: POST /api/Cart/AddItemToCart
Add multiple items at once
For better performance when adding multiple items, use AddItemsToCart:
Endpoint: POST /api/Cart/AddItemsToCart
Update quantity
Update the quantity of an existing line item by SKU or line item ID.
By SKU: POST /api/Cart/{cartId}/OrderLines/SetQuantity/Sku/{skuId}/{quantity}
By LineItemId: POST /api/Cart/{cartId}/OrderLines/SetQuantity/OrderLineId/{orderLineId}/{quantity}
Setting quantity to 0 removes the item from the cart. For bundle products, the quantity of all component items is automatically recalculated.
Remove item
Endpoint: DELETE /api/Cart/{cartId}/OrderLines/{lineItemId}
For bundle products, add ?deleteComponents=true to remove all component line items as well.
Apply coupon code
Endpoint: PUT /api/Cart/{cartId}/AddCouponCode/{couponCode}
The cart is automatically recalculated with the promotion applied. If the coupon is invalid or expired, a 400 Bad Request is returned.
Apply gift card
Endpoint: PUT /api/Cart/{cartId}/AddGiftCard/{giftCardCode}
For gift cards with a PIN, add it as a query parameter:
Step 3: Checkout
Get shipping options
Fetch available shipping methods for the cart based on the delivery address.
Endpoint: GET /api/Cart/{cartId}/GetShippingOptions
| Parameter | Type | Description |
|---|---|---|
| postalCode | string | Delivery postal code (for calculating shipping) |
Example response:
Add shipment
Add the customer's selected shipping method to the cart.
Endpoint: PUT /api/Cart/{cartId}/AddShipments
Standard home delivery:
Click and collect (pickup in store):
| Property | Type | Required | Description |
|---|---|---|---|
| shipmentId | string | Yes | Unique ID for the shipment (can be "1" or a GUID) |
| shippingMethodName | string | Yes | Must match a configured shipping method |
| warehouseCode | string | Yes | Store ID that will fulfill the order |
| pickUpWarehouseCode | string | No | Store ID for pickup (click & collect only) |
Get payment options
Fetch available payment methods for the cart.
Endpoint: GET /api/Cart/{cartId}/GetPaymentOptions
Example response:
Add payment
Register a payment transaction on the cart. This is typically done after the customer completes payment with your payment provider.
Endpoint: PUT /api/Cart/{cartId}/AddPayments
E-commerce payment (authorization):
POS payment (immediate capture):
Split payment (gift card + card):
| Property | Type | Required | Description |
|---|---|---|---|
| amount | decimal | Yes | Payment amount in the cart's currency |
| paymentMethodName | string | Yes | Must match a configured payment method |
| transactionId | string | Yes | Payment provider's transaction reference |
| transactionType | string | Yes | "Authorization" (e-commerce) or "Sale" (POS) |
| status | string | Yes | Typically "Processed" |
For e-commerce, use transactionType: "Authorization". Omnium workflows handle capture and credit automatically when the order is fulfilled or returned.
Add customer
Associate a customer with the cart. This enables customer-specific pricing and saves the order to the customer's order history.
Endpoint: PUT /api/Cart/{cartId}/AddCustomer/{customerId}
| Parameter | Type | Description |
|---|---|---|
| enrichCart | bool | Copy customer name and contact info to cart |
| isPriceRecalculated | bool | Recalculate prices based on customer tier |
| customerSpecificPrices | bool | Apply customer-specific contract prices |
Validate cart
Before creating an order, validate the cart to catch any issues.
Endpoint: POST /api/Cart/{cartId}/Validate
Success response (200 OK):
Validation issues (422 Unprocessable Entity):
Built-in validators check inventory, active products, payment totals, and more. See Cart Configuration for the full list.
Step 4: Create order
Convert the cart into an order to trigger fulfillment workflows.
Endpoint: POST /api/Cart/CreateOrderFromCart/{cartId}
| Parameter | Type | Description |
|---|---|---|
| orderType | string | Order type (e.g., "Online", "ClickAndCollect") |
Example response:
The order is now created and workflow steps (notifications, ERP sync, etc.) will execute based on your order type configuration.
Additional endpoints
Get cart
Retrieve an existing cart by ID.
Endpoint: GET /api/Cart/{cartId}
Get carts by customer
Retrieve the latest carts for a customer (returns up to 50).
Endpoint: GET /api/Cart/GetCartsByCustomer
Search carts
Search for carts with filters.
Endpoint: POST /api/Cart/Search
Save complete cart
Create or update a cart with a complete cart object. Use this when your system already has prices and metadata.
Endpoint: PUT /api/Cart
Recalculate prices
Force recalculation of all prices on the cart (useful after price updates).
Endpoint: PUT /api/Cart/{cartId}/RecalculatePrices
Delete cart
Permanently delete a cart.
Endpoint: DELETE /api/Cart/{cartId}
Deleted carts cannot be recovered. Use DeactivateCart if you want to hide the cart without permanent deletion.
Bundle and package products
Omnium supports bundle products (fixed product combinations) and package products (configurable components).
Add bundle to cart
Endpoint: POST /api/Cart/AddBundleToCart
If the bundle contains products with variants, specify the selected variants in the request body:
Update bundle components
Update variant selections for a bundle already in the cart.
Endpoint: POST /api/Cart/{cartId}/UpdateComponentsInCart/orderLineId/{orderLineId}
Product options and customizations
Add product options like engraving or gift wrapping to an existing line item.
Endpoint: POST /api/Cart/AddProductOptionsItemToCart
Product options are added as separate line items linked to the parent product.
Units of measure (B2B)
For B2B scenarios where products can be sold in different units (each, box, pallet), use the unit-aware endpoints.
Add item with unit
Update unit quantity
Endpoint: POST /api/Cart/{cartId}/OrderLines/SetSelectedUnitQuantity/Sku/{skuId}/{selectedUnit}/{selectedUnitQuantity}
The actual quantity is calculated as: selectedUnitQuantity × conversionFactor
Error handling
The Cart API uses standard HTTP status codes:
| Status | Meaning |
|---|---|
| 200 | Success |
| 201 | Created (new cart) |
| 400 | Bad request (invalid parameters) |
| 404 | Cart or resource not found |
| 422 | Validation errors (cart returned with errors) |
| 500 | Server error |
Error response format
Validation error response
Complete checkout example
Here's a realistic example of a cart service that mirrors the customer journey. Each method represents a separate user action that happens at different times during the shopping session.
Example: Customer journey through your e-commerce site
Remember to configure authentication headers on the HttpClient. See the Authentication documentation for details.
