Storefront Checkout

const { products } = await storefront.products.listProducts({ limit: 20 });

const { products } = await storefront.products.listProducts({
  limit: 20,
  fields: 'id,name,price,sale_price,media',
});
// Each product now carries only those keys. Conversely, full: true returns the
// complete object (media, specifications, every variant) for a product detail page.

let cursor: string | undefined;
do {
  const page = await storefront.products.listProducts({ limit: 50, cursor });
  // …render page.products…
  cursor = page.pagination.has_more ? page.pagination.next_cursor : undefined;
} while (cursor);

const { products } = await storefront.products.listProducts({
  categoryId: '…category-uuid…',
  limit: 20,
});

const sessionId = crypto.randomUUID(); // generate once, store in a cookie

const cart = await storefront.cartWishlist.addToCart({
  xSessionId: sessionId,
  requestBody: { variant_id: 'e98631a9-7852-4fe8-8efe-988935d5922a', quantity: 2 },
});

const cart = await storefront.cartWishlist.getCart({ xSessionId: sessionId });
// → { items: [...], total_items: 2, subtotal: 598 }

await storefront.cartWishlist.updateCartItem({
  id: '09695de2-73ac-45ea-b2cb-76f9751b9846', // the cart-item id from the add response
  xSessionId: sessionId,
  requestBody: { quantity: 3 },
});

await storefront.cartWishlist.removeCartItem({
  id: '09695de2-73ac-45ea-b2cb-76f9751b9846',
  xSessionId: sessionId,
});
// → { success: true, message: 'Item removed from cart' }

await storefront.cartWishlist.clearCart({ xSessionId: sessionId });
// → { success: true, message: 'Cart cleared' }

// On your server
const { customer, session } = await server.authentication.login({
  requestBody: { email: 'john.doe@example.com', password: '••••••••' },
});
// Hand session.access_token back to the browser to use as xAuthToken.

const merged = await storefront.cartWishlist.mergeCart({
  xAuthToken: session.access_token,
  requestBody: { session_id: sessionId, customer_id: customer.id },
});
// merged.customer_id === customer.id  → the cart now belongs to the signed-in shopper

const quote = await storefront.shipping.calculateShipping({
  requestBody: { latitude: 40.6782, longitude: -73.9442, order_total: 598 },
});

const quote = await storefront.shipping.calculateShipping({
  requestBody: {
    latitude: 40.748, longitude: -73.985, order_total: 598,
    address_to: { street1: '350 5th Ave', city: 'New York', state: 'NY', zip: '10118', country: 'US' },
    parcel: { length: '10', width: '8', height: '4', distance_unit: 'in', weight: '2', mass_unit: 'lb' },
  },
});

const { reservation_ids } = await storefront.orders.reserveStock({
  requestBody: {
    items: [{ variant_id: 'e98631a9-7852-4fe8-8efe-988935d5922a', quantity: 2 }],
    ttl_seconds: 900,
  },
});

import { createHmac } from 'crypto';

const timestamp = Math.floor(Date.now() / 1000);
const orderData = {
  customer_email: 'john.doe@example.com',
  customer_name: 'John Doe',
  shipping_address: { street: '350 Fifth Avenue', city: 'New York', state: 'NY', zip: '10118', country: 'US' },
  items: [
    { product_id: '0186665f-f0a1-4c79-976a-919b5b1c2daa', variant_id: 'e98631a9-7852-4fe8-8efe-988935d5922a', quantity: 2, unit_price: 299, total_price: 598 },
  ],
  subtotal: 598,
  shipping_amount: 5.99,
  discount_amount: 0,
  // With automatic tax enabled, omit tax_amount — Galactic Core calculates it for the
  // shipping destination. total_amount must be the FINAL tax-inclusive total
  // (subtotal + tax + shipping − discount); preview the tax first with the Tax preview
  // endpoint (see the Tax guide) so the storefront shows and submits the right total.
  // Here NY tax on $598 is $53.08, so total = 598 + 53.08 + 5.99 = 657.07.
  total_amount: 657.07,
  payment_status: 'pending',
};

// Sign with `${timestamp}.${JSON.stringify(body)}`, HMAC-SHA256, base64.
const sign = (body: object, ts: number) =>
  createHmac('sha256', process.env.TYBRITE_HMAC_SECRET)
    .update(`${ts}.${JSON.stringify(body)}`)
    .digest('base64');

const { order } = await server.orders.createOrder({
  idempotencyKey: `order-${customer.id}-${timestamp}`,
  xTimestamp: timestamp,
  xSignature: sign(orderData, timestamp),
  requestBody: orderData,
});

const ts2 = Math.floor(Date.now() / 1000);
const orderWithPromo = {
  ...orderData,
  discount_amount: 89.70,
  total_amount: 514.29, // 598 − 89.70 + 5.99
  promotion_usages: [
    { promotion_id: 'df290d89-0400-4b2c-aa56-11fcc486150c', discount_amount: 89.70 },
  ],
};

const { order: promoOrder } = await server.orders.createOrder({
  idempotencyKey: `order-${customer.id}-${ts2}`,
  xTimestamp: ts2,
  xSignature: sign(orderWithPromo, ts2),
  requestBody: orderWithPromo,
});
// promoOrder.discount_amount === 89.7  ·  promoOrder.total_amount === 514.29

const ts3 = Math.floor(Date.now() / 1000);
const orderWithGiftCard = {
  ...orderWithPromo,
  discount_amount: 139.70,                                  // promo 89.70 + gift card 50
  total_amount: 464.29,                                     // 598 + 5.99 − 139.70
  gift_card_redemption: { code: 'GTSA-1B2C-3D4E-5F6G', amount: 50 },
};

const { order: gcOrder, post_processing_warnings } = await server.orders.createOrder({
  idempotencyKey: `order-${customer.id}-${ts3}`,
  xTimestamp: ts3,
  xSignature: sign(orderWithGiftCard, ts3),
  requestBody: orderWithGiftCard,
});
// gcOrder.total_amount === 464.29  ·  post_processing_warnings === []  (gift card + stock OK)

// discount_amount includes the $50 gift card, but total_amount wasn't lowered to match
const bad = { ...orderWithGiftCard, total_amount: 514.29 }; // should be 464.29
await server.orders.createOrder({ /* …signed… */, requestBody: bad });

// $598 cart, but claim a $290 discount with no promotion (or an over-stated one)
const bogus = { ...orderData, discount_amount: 290, total_amount: 308 };
await server.orders.createOrder({ /* …signed… */, requestBody: bogus });

const withBadCard = { ...orderWithPromo, payment_status: 'paid', gift_card_redemption: { code: 'NOPE-0000-0000-0000', amount: 50 } };
const { order, post_processing_warnings } = await server.orders.createOrder({ /* …signed… */, requestBody: withBadCard });
// order.id exists (201) — but post_processing_warnings is NON-empty. Handle it.

const payment = await server.payments.initializePayment({
  idempotencyKey: `pay-${gcOrder.id}`,
  xTimestamp: Math.floor(Date.now() / 1000),
  xSignature: paymentSignature, // sign the payment body the same way as the order
  requestBody: {
    provider: 'stripe',
    amount: 464.29, // gcOrder.total_amount from step 7c
    currency: 'usd',
    email: 'john.doe@example.com',
    success_url: 'https://example.com/payment-success',
    cancel_url: 'https://example.com/payment-cancelled',
  },
});

// Redirect the shopper to payment.checkout_url

const trackingUrl = order.shipping_metadata?.shippo?.tracking_url;
{trackingUrl && <a href={trackingUrl} target="_blank" rel="noopener noreferrer">Track your package</a>}

const status = await storefront.shipping.trackShipment({ carrier: 'usps', number: order.tracking_number });
// → { carrier, tracking_number, status, eta, history: [...] }