Skip to main content

Cart API Reference

The Cart module provides comprehensive shopping cart management functionality including creating carts, managing line items, and handling cart operations.

Overview​

The Cart API allows you to:

  • Create and manage shopping carts
  • Add, update, and remove line items
  • Handle multi-supplier cart scenarios
  • Track cart state and totals
import SdkService from '../services/SdkService';

// Access cart methods
const cart = SdkService.sdk.cart;

Methods​

create()​

Creates a new shopping cart for a customer session.

create(params: {
 customer_session_id: string;
 currency: string;
 shippingCountry?: string;
}): Promise<CreateCartDto>

Parameters​

ParameterTypeRequiredDescription
customer_session_idstringYesUnique identifier for the customer session
currencystringYesISO currency code (e.g., 'USD', 'EUR', 'NOK')
shippingCountrystringNoISO country code for shipping calculation

Example​

const cart = await SdkService.sdk.cart.create({
 customer_session_id: 'session_12345',
 currency: 'USD',
 shippingCountry: 'US'
});

console.log('Cart created:', cart.cart_id);

Response​

interface CreateCartDto {
 cart_id: string;
 customer_session_id: string;
 currency: string;
 line_items: LineItem[];
 total_price: number;
 shipping_country?: string;
 created_at: string;
 updated_at: string;
}

getById()​

Retrieves a cart by its ID with all current line items and totals.

getById(params: {
 cart_id: string;
}): Promise<GetCartDto>

Parameters​

ParameterTypeRequiredDescription
cart_idstringYesThe unique identifier of the cart

Example​

const cart = await SdkService.sdk.cart.getById({
 cart_id: 'cart_67890'
});

console.log('Cart details:', cart);
console.log('Total items:', cart.line_items.length);
console.log('Total price:', cart.total_price);

Response​

interface GetCartDto {
 cart_id: string;
 customer_session_id: string;
 currency: string;
 line_items: LineItem[];
 total_price: number;
 subtotal_price: number;
 total_tax: number;
 shipping_country?: string;
 created_at: string;
 updated_at: string;
}

update()​

Updates cart properties such as shipping country.

update(params: {
 cart_id: string;
 shipping_country: string;
}): Promise<UpdateCartDto>

Parameters​

ParameterTypeRequiredDescription
cart_idstringYesThe unique identifier of the cart
shipping_countrystringYesISO country code for shipping

Example​

const updatedCart = await SdkService.sdk.cart.update({
 cart_id: 'cart_67890',
 shipping_country: 'NO'
});

console.log('Cart updated with new shipping country');

addItem()​

Adds a product as a line item to the cart.

addItem(params: {
 cart_id: string;
 line_items: {
 product_id: number;
 variant_id?: number;
 quantity: number;
 };
}): Promise<CreateItemToCartDto>

Parameters​

ParameterTypeRequiredDescription
cart_idstringYesThe unique identifier of the cart
line_items.product_idnumberYesID of the product to add
line_items.variant_idnumberNoID of the product variant (if applicable)
line_items.quantitynumberYesQuantity of the product to add

Example​

const cartWithItem = await SdkService.sdk.cart.addItem({
 cart_id: 'cart_67890',
 line_items: {
 product_id: 12345,
 variant_id: 67890,
 quantity: 2
 }
});

console.log('Item added to cart');
console.log('New total:', cartWithItem.total_price);

Response​

interface CreateItemToCartDto {
 cart_id: string;
 line_items: LineItem[];
 total_price: number;
 subtotal_price: number;
 // ... other cart properties
}

updateItem()​

Updates the quantity or shipping method of an existing line item in the cart.

updateItem(params: {
 cart_id: string;
 cart_item_id: string;
 quantity?: number;
 shipping_id?: string;
}): Promise<UpdateItemToCartDto>

Parameters​

ParameterTypeRequiredDescription
cart_idstringYesThe unique identifier of the cart
cart_item_idstringYesThe ID of the line item to update
quantitynumberNoNew quantity for the line item
shipping_idstringNoID of the shipping method to use

Example​

const updatedCart = await SdkService.sdk.cart.updateItem({
 cart_id: 'cart_67890',
 cart_item_id: 'item_123',
 quantity: 3,
 shipping_id: 'shipping_456'
});

console.log('Line item updated');

deleteItem()​

Removes a line item from the cart.

deleteItem(params: {
 cart_id: string;
 cart_item_id: string;
}): Promise<RemoveItemToCartDto>

Parameters​

ParameterTypeRequiredDescription
cart_idstringYesThe unique identifier of the cart
cart_item_idstringYesThe ID of the line item to remove

Example​

const cartAfterRemoval = await SdkService.sdk.cart.deleteItem({
 cart_id: 'cart_67890',
 cart_item_id: 'item_123'
});

console.log('Item removed from cart');
console.log('Remaining items:', cartAfterRemoval.line_items.length);

delete()​

Permanently deletes the entire cart and all its line items.

delete(params: {
 cart_id: string;
}): Promise<RemoveCartDto>

Parameters​

ParameterTypeRequiredDescription
cart_idstringYesThe unique identifier of the cart

Example​

const result = await SdkService.sdk.cart.delete({
 cart_id: 'cart_67890'
});

console.log('Cart deleted successfully');

getLineItemsBySupplier()​

Retrieves line items grouped by supplier for multi-vendor scenarios.

getLineItemsBySupplier(params: {
 cart_id: string;
}): Promise<GetLineItemsBySupplierDto[]>

Parameters​

ParameterTypeRequiredDescription
cart_idstringYesThe unique identifier of the cart

Example​

const itemsBySupplier = await SdkService.sdk.cart.getLineItemsBySupplier({
 cart_id: 'cart_67890'
});

itemsBySupplier.forEach(supplier => {
 console.log(`Supplier: ${supplier.supplier_name}`);
 console.log(`Items: ${supplier.line_items.length}`);
 console.log(`Total: ${supplier.total_price}`);
});

Response​

interface GetLineItemsBySupplierDto {
 supplier_id: string;
 supplier_name: string;
 line_items: LineItem[];
 total_price: number;
 shipping_options: ShippingOption[];
}

Type Definitions​

LineItem​

interface LineItem {
 id: string;
 product_id: number;
 variant_id?: number;
 product_title: string;
 variant_title?: string;
 quantity: number;
 price: number;
 total_price: number;
 sku?: string;
 barcode?: string;
 image_url?: string;
 shipping_id?: string;
 supplier_id: string;
 supplier_name: string;
}

ShippingOption​

interface ShippingOption {
 id: string;
 name: string;
 price: number;
 estimated_delivery: string;
 carrier: string;
}

Error Handling​

All cart methods can throw the following types of errors:

try {
 const cart = await SdkService.sdk.cart.create({
 customer_session_id: 'session_123',
 currency: 'USD'
 });
} catch (error) {
 if (error.graphQLErrors) {
 // Handle GraphQL-specific errors
 console.error('GraphQL Error:', error.graphQLErrors[0].message);
 } else if (error.networkError) {
 // Handle network errors
 console.error('Network Error:', error.networkError);
 } else {
 // Handle other errors
 console.error('Unknown Error:', error);
 }
}

Common Error Scenarios​

ErrorDescriptionSolution
CART_NOT_FOUNDCart ID doesn't existVerify the cart ID is correct
PRODUCT_NOT_AVAILABLEProduct is out of stockCheck product availability
INVALID_CURRENCYUnsupported currency codeUse supported currency codes
INVALID_QUANTITYQuantity is zero or negativeEnsure quantity is positive

Best Practices​

1. Session Management​

// Use consistent session IDs for the same user
const sessionId = `user_${userId}_${Date.now()}`;

2. Error Recovery​

// Implement retry logic for network failures
const createCartWithRetry = async (params, retries = 3) => {
 for (let i = 0; i < retries; i++) {
 try {
 return await SdkService.sdk.cart.create(params);
 } catch (error) {
 if (i === retries - 1) throw error;
 await new Promise(resolve => setTimeout(resolve, 1000 * i));
 }
 }
};

3. Cart Persistence​

// Save cart ID to AsyncStorage for persistence
import AsyncStorage from '@react-native-async-storage/async-storage';

const saveCartId = async (cartId: string) => {
 await AsyncStorage.setItem('cart_id', cartId);
};

const getCartId = async (): Promise<string | null> => {
 return await AsyncStorage.getItem('cart_id');
};

  • Checkout API - Convert carts to checkouts
  • Products API - Browse available products (coming soon)
  • Payment API - Process cart payments