E-shop

The E-shop module provides complete e-commerce functionality including product management, order processing, and checkout.

Products

Create Product

Create a new product. New products start in the active state.

const result = await sdk.eshop.createProduct({
key: 'premium-widget',
slug: { en: 'premium-widget' },
taxonomies: [
  { taxonomyId: 'tax_category', entryIds: ['ent_widgets'] }
],
blocks: [
  {
    key: 'details',
    type: 'TEXT',
    content: {
      body: { en: 'Product specifications...' }
    }
  }
],
variants: [
  {
    sku: 'WIDGET-SM',
    prices: [{ market: 'USD', amount: 2999 }],
    inventory: [{ locationId: 'loc_warehouse', available: 100 }],
    attributes: [],
    weight: 500
  },
  {
    sku: 'WIDGET-LG',
    prices: [{ market: 'USD', amount: 3999 }],
    inventory: [{ locationId: 'loc_warehouse', available: 50 }],
    attributes: [],
    weight: 750
  }
]
});

Get Product

Retrieve a product by ID or slug.

// By ID
const result = await sdk.eshop.getProduct({
  id: 'prod_xyz789'
});

// By slug (locale-aware)
const result = await sdk.eshop.getProduct({
  slug: 'premium-widget'
});

List Products

List products with filtering and pagination.

const result = await sdk.eshop.getProducts({
ids: ['prod_1', 'prod_2'],
taxonomyQuery: [
  { taxonomyId: 'tax_category', entryIds: ['ent_widgets'] }
],
matchAll: true,
status: 'active',
query: 'premium',
sortField: 'createdAt',
sortDirection: 'desc',
cursor: null,
limit: 20,
createdAtFrom: 1704067200,
createdAtTo: 1706745600
});

const { items, cursor } = result;
items.forEach(product => {
console.log(product.key, product.variants);
});

Update Product

Update an existing product. Use status to archive or re-activate a product.

const result = await sdk.eshop.updateProduct({
  id: 'prod_xyz789',
  key: 'updated-widget',
  slug: { en: 'updated-widget', es: 'widget-actualizado' },
  taxonomies: [
    { taxonomyId: 'tax_category', entryIds: ['ent_widgets', 'ent_sale'] }
  ],
  blocks: [/* updated blocks */],
  variants: [
    {
      id: 'var_existing',
      sku: 'WIDGET-SM-V2',
      prices: [{ market: 'USD', amount: 3499 }],
      inventory: [{ locationId: 'loc_warehouse', available: 150 }],
      attributes: [],
      weight: 500
    }
  ],
  status: 'active'
});

Delete Product

Delete a product.

await sdk.eshop.deleteProduct({
  id: 'prod_xyz789'
});

Orders

Create Order

Create a new order without payment processing (use checkout for payment). Created orders start with status: 'active' and workflowStatus: 'created'.

const result = await sdk.eshop.createOrder({
  market: 'USD',
  customerId: 'acc_customer123',
  items: [
    { productId: 'prod_xyz789', variantId: 'var_small', quantity: 2 },
    { productId: 'prod_abc456', variantId: 'var_default', quantity: 1 }
  ],
  shippingAddress: {
    name: 'Jane Doe',
    street1: '456 Customer Ave',
    city: 'New York',
    state: 'NY',
    postalCode: '10001',
    country: 'US'
  },
  forms: [
    {
      key: 'shipping-notes',
      entries: [{ key: 'note', value: 'Leave at door' }]
    }
  ]
});

Get Order

Retrieve an order by ID.

const order = await sdk.eshop.getOrder({
  id: 'ord_xyz789'
});

console.log(order.status, order.workflowStatus, order.total, order.items);

List Orders

List orders with filtering. Orders have two status fields: status (active / archived) for soft archival, and workflowStatus for the payment/fulfillment lifecycle.

const result = await sdk.eshop.getOrders({
customerId: 'acc_customer123',
status: 'active',
workflowStatus: 'confirmed',
productIds: ['prod_xyz789'],
query: 'john@example.com',
sortField: 'createdAt',
sortDirection: 'desc',
cursor: null,
limit: 50,
createdAtFrom: 1704067200,
createdAtTo: 1735689600
});

result.items.forEach(order => {
console.log(order.id, order.status, order.workflowStatus, order.total);
});

Update Order

Update an order’s archival state, workflow status, addresses, form entries, items, or payment.

// Advance the workflow
await sdk.eshop.updateOrder({
id: 'ord_xyz789',
workflowStatus: 'confirmed'
});

// Archive an order
await sdk.eshop.updateOrder({
id: 'ord_xyz789',
status: 'archived'
});

// Update addresses / form entries
await sdk.eshop.updateOrder({
id: 'ord_xyz789',
shippingAddress: {
  name: 'Jane Doe',
  street1: '456 Customer Ave',
  city: 'New York',
  state: 'NY',
  postalCode: '10001',
  country: 'US'
},
forms: [
  { key: 'notes', entries: [{ key: 'note', value: 'Leave at door' }] }
],
items: [
  { productId: 'prod_xyz', variantId: 'var_1', quantity: 2 }
]
});

Checkout

Get Quote

Calculate order total before checkout. The SDK injects market automatically from the client config.

const quote = await sdk.eshop.getQuote({
items: [
  { productId: 'prod_xyz789', variantId: 'var_small', quantity: 2 }
],
paymentMethodId: 'pm_card_visa',
shippingMethodId: 'ship_standard',
promoCode: 'SAVE10',
location: {
  country: 'US',
  state: 'NY',
  postalCode: '10001'
}
});

console.log('Subtotal:', quote.subtotal);
console.log('Discount:', quote.discount);
console.log('Shipping:', quote.shipping);
console.log('Tax:', quote.tax);
console.log('Total:', quote.total);

Checkout

Process payment and complete an order. The SDK injects businessId and market from the client config. The checkout response includes orderId, order number, a Stripe clientSecret (when 3DS or additional confirmation is required), and the payment object.

const result = await sdk.eshop.checkout({
items: [
  { productId: 'prod_xyz789', variantId: 'var_small', quantity: 2 }
],
paymentMethodId: 'pm_card_visa',
shippingMethodId: 'ship_standard',
shippingAddress: {
  name: 'Jane Doe',
  street1: '456 Customer Ave',
  city: 'New York',
  state: 'NY',
  postalCode: '10001',
  country: 'US'
},
forms: [
  {
    key: 'customer-info',
    entries: [
      { key: 'email', value: 'customer@example.com' },
      { key: 'firstName', value: 'John' },
      { key: 'lastName', value: 'Doe' }
    ]
  }
],
promoCodeId: 'promo_save10'
});

if (result.clientSecret) {
// Additional confirmation (e.g. 3D Secure) required on the client
const { error } = await stripe.confirmCardPayment(result.clientSecret);
if (error) throw new Error(error.message);
}

console.log('Order placed:', result.orderId, result.number);

Complete Checkout Flow

import { loadStripe } from '@stripe/stripe-js';

const stripe = await loadStripe('pk_live_xxx');

async function checkout(cart: CartItem[]) {
  // 1. Get quote to show prices
  const quote = await sdk.eshop.getQuote({
    items: cart.map(item => ({
      productId: item.productId,
      variantId: item.variantId,
      quantity: item.quantity
    })),
    shippingMethodId: selectedShipping,
    promoCode: promoCodeInput
  });

  console.log('Total:', quote.total);

  // 2. Create Stripe payment method
  const { paymentMethod, error } = await stripe.createPaymentMethod({
    type: 'card',
    card: cardElement,
    billing_details: {
      email: customerEmail
    }
  });

  if (error) {
    throw new Error(error.message);
  }

  // 3. Checkout
  const result = await sdk.eshop.checkout({
    items: cart.map(item => ({
      productId: item.productId,
      variantId: item.variantId,
      quantity: item.quantity
    })),
    paymentMethodId: paymentMethod.id,
    shippingMethodId: selectedShipping,
    shippingAddress,
    forms: [
      {
        key: 'customer',
        entries: [
          { key: 'email', value: customerEmail },
          { key: 'firstName', value: customerFirstName },
          { key: 'lastName', value: customerLastName }
        ]
      }
    ],
    promoCodeId: appliedPromoId
  });

  if (result.clientSecret) {
    // Handle 3D Secure / additional confirmation
    const { error } = await stripe.confirmCardPayment(result.clientSecret);
    if (error) throw new Error(error.message);
  }

  return result.orderId;
}