Every Method by Task

// A single product by slug (storefront route → product page)
const { product } = await storefront.products.getProductBySlug({ slug: 'samsung-galaxy-watch-6-0186' });
// → product.id === '0186665f-f0a1-4c79-976a-919b5b1c2daa', product.price === 299

// The latest published specifications for a VARIANT (the spec sheet).
// NOTE: this endpoint is keyed by VARIANT id, not product id — pass a variant_id
// (e.g. from getProduct().variants[].variant_id). A product id returns 404.
const specs = await storefront.products.getProductSpecifications({ id: '9a47e047-b1b6-4c35-9617-820629e22e04' });

// The merchant's OWN fields on a product — whatever they chose to record beyond the
// built-in attributes. Only fields they published are returned, and the set differs per
// store, so render what comes back rather than reading fixed keys.
const { custom_fields } = await storefront.products.getProductCustomFields({ id: '02525ff5-0916-4f00-857c-c2c6237e671b' });
// → [{ field_name: 'care_instructions', field_label: 'Care instructions', field_type: 'text', value: 'Machine wash at 30' }]
// See /custom-fields for the types and the records that carry them.

// All specs across the catalog (admin-style export / spec search). Each row carries
// the variant_id it belongs to (specs are variant-keyed).
const allSpecs = await storefront.products.listProductSpecifications({ limit: 50 });
// → { specifications: [{ id, variant_id, template_id, specification_data, status, version, ... }], pagination: { has_more: true, next_cursor: "..." } }

// Curated collections ("Best Sellers", "New Arrivals")
const { collections } = await storefront.products.listProductCollections();
// → collections[0] === { id: '1f0e...', name: 'Best Sellers', slug: 'best-sellers', product_count: 12 }

const collection = await storefront.products.getProductCollection({ id: '1f0e8d2a-...' });
// → { id, name: 'Best Sellers', description, slug }

const items = await storefront.products.getProductCollectionItems({ id: '1f0e8d2a-...', limit: 20 });
// → { items: [] } — collections are rule-based; members resolve server-side, so items is empty
//    unless the collection has explicitly materialized members.

// A single category, and one subcategory with its subtree
const category = await storefront.taxonomy.getCategory({ id: '3310356e-7ca4-4056-93b4-80c612536b5d' });
// → { id, name: 'Wearables', description: 'Smartwatches, fitness trackers, wearable tech', active: true, image: '...' }

const subcategory = await storefront.taxonomy.getSubcategory({ id: '7d9b...', include: 'children' });
// → { id, name: 'Smartwatches', parent_id, children: [{ id, name }] }

// Price one product by slug (with geographic currency detection). Returns the full
// product object plus pricing fields: base_price (USD), display_price + display_currency
// (after rules + currency conversion), price_breakdown, and pricing_context.
const price = await storefront.pricing.getProductPriceBySlug({ slug: 'samsung-galaxy-watch-6-0186', placeName: 'London' });
// → { product_id: '0186665f-...', base_price: 299, base_currency: 'USD',
//     resolved_price: 269.1, display_price: 212.59, display_currency: 'GBP',
//     exchange_rate: 0.79, price_breakdown: { ... }, pricing_context: { region: 'United Kingdom', currency: 'GBP', ... } }

// List the store's active promotions
const { promotions } = await storefront.promotions.listPromotions({ limit: 10 });

// One promotion's detail
const promo = await storefront.promotions.getPromotion({ id: 'df290d89-0400-4b2c-aa56-11fcc486150c' });
// → { id, name: 'Spring Sale — 15% Off', value: '15', min_purchase: 50, status: 'active' }

// What a specific promotion takes off a cart (server does the math).
// The cart lines are { product_id, quantity, price }.
const applied = await storefront.promotions.calculatePromotionDiscount({
  id: 'df290d89-0400-4b2c-aa56-11fcc486150c',
  requestBody: { cart: [{ product_id: '7d425c0a-50e7-4e39-af79-6f7945f9dfa8', quantity: 1, price: 349.99 }] },
});
// → { promotion_id: 'df290d89-...', type: 'discount', eligible: true, discount: 52.5, reason: null }

// The single best promotion across all active rules for this cart
const best = await storefront.promotions.calculateBestPromotion({
  requestBody: { cart: [{ product_id: '7d425c0a-...', quantity: 1, price: 349.99 }, { product_id: '0186665f-...', quantity: 1, price: 299 }] },
});
// → { promotion: { id, name: 'Audio + Wearable Bundle', type: 'bundle' }, discount: 100 }

// Read a cart (anonymous by session, or a customer's)
const cart = await storefront.cartWishlist.getCart({ xSessionId: sessionId });
// → { items: [{ id, product_name, quantity, total_price }], session_id, customer_id: null }

await storefront.cartWishlist.updateCartItem({ id: '09695de2-...', xSessionId: sessionId, requestBody: { quantity: 3 } });
// → { items: [{ id: '09695de2-...', quantity: 3, total_price: 897 }] }

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

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

// Wishlist (always customer-scoped → xAuthToken)
await storefront.cartWishlist.addToWishlist({ xAuthToken: token, requestBody: { variant_id: 'e98631a9-...', customer_id: customerId } });
// → 201 { items: [{ id, product_name: 'Samsung Galaxy Watch 6' }] }

const wishlist = await storefront.cartWishlist.getWishlist({ xAuthToken: token, customerId });
// → { items: [{ id: '...', variant_id: 'e98631a9-...', product_name: 'Samsung Galaxy Watch 6' }] }

await storefront.cartWishlist.moveWishlistToCart({ xAuthToken: token, requestBody: { wishlist_item_id: '...', customer_id: customerId, quantity: 1 } });
// → { success: true, removed_wishlist_item_id: '...', items: [...] }

await storefront.cartWishlist.removeFromWishlist({ id: '...', xAuthToken: token, customerId });
// → { success: true, message: 'Item removed from wishlist' }

// Create a customer directly (server-driven signup)
const customer = await server.customers.createCustomer({
  requestBody: { name: 'John Doe', email: 'john.doe@example.com', phone: '+12125550142' },
});
// → 201 { id: '15ecd58f-...', name: 'John Doe', tier: 'bronze', total_purchases: 0, address: null }

await server.customers.updateCustomer({ id: '15ecd58f-...', xAuthToken: token, requestBody: { phone: '+12125550199' } });
// → 200 { id: '15ecd58f-...', phone: '+12125550199' }

// The customer's saved address book. Address fields are line1/line2/postal_code,
// with separate is_default_shipping / is_default_billing flags.
const { addresses } = await storefront.customers.listAddresses({ id: customerId, xAuthToken: token });
// → { addresses: [{ id, label: 'Home', line1: '350 Fifth Avenue', city: 'New York', is_default_shipping: true, is_default_billing: true }] }

const { address } = await storefront.customers.createAddress({
  id: customerId, xAuthToken: token,
  requestBody: { full_name: 'John Doe', label: 'Work', line1: '350 Fifth Avenue', city: 'New York', state: 'NY', postal_code: '10118', country: 'US', address_type: 'both', is_default_shipping: true, is_default_billing: true },
});
// → 201 { address: { id, customer_id, address_type: 'both', label: 'Work', full_name: 'John Doe', line1, city, state, postal_code, country, is_default_shipping: true, is_default_billing: true, created_at, updated_at } }

await storefront.customers.updateAddress({ id: customerId, addressId: address.id, xAuthToken: token, requestBody: { label: 'Office', line2: 'Suite 2100' } });
// → 200 { address: { id, label: 'Office', line2: 'Suite 2100', ... } }

await storefront.customers.deleteAddress({ id: customerId, addressId: address.id, xAuthToken: token });
// → { success: true, message: 'Address deleted' }

// Register (the sign-up half of the login flow)
const created = await server.authentication.register({
  requestBody: { name: 'John Doe', email: 'john.doe@example.com', password: '••••••••' },
});
// → 201 { user: { id, email, email_confirmed: false }, customer: { id, tier: 'bronze' }, session: { access_token: 'eyJ...<redacted>.signature' } }

// Who is this token? (hydrate "My Account")
const me = await server.authentication.getCurrentUser({ xAuthToken: token });
// → { user: { id: 'df648f68-...', email: 'john.doe@example.com' }, customer: { id: '15ecd58f-...', name: 'John Doe' } }

// Rotate the session before it expires (~1h)
const refreshed = await server.authentication.refreshToken({ requestBody: { refresh_token: '5h2g7k9m...' } });
// → { message: 'Token refreshed successfully', session: { access_token: 'eyJ...<redacted>.signature', refresh_token: '...', expires_in: 3600, expires_at: 1782040572 } }

// End the session
await server.authentication.logout({ xAuthToken: token });
// → { message: 'Logout successful' }

// Password reset (request a reset email → set a new password)
await server.authentication.resetPassword({ requestBody: { email: 'john.doe@example.com' } });
// → { message: 'Password reset email sent', email: 'john.doe@example.com' }

await server.authentication.updatePassword({ xAuthToken: token, requestBody: { password: '••••••••' } });
// → { message: 'Password updated successfully', user: { id: 'df648f68-...', email: 'john.doe@example.com' } }

// Passwordless: OTP verification signs the customer in (same envelope as login)
const verified = await server.authentication.verifyOtp({ requestBody: { email: 'john.doe@example.com', token: '123456' } });
// → { message: 'OTP verified successfully', user: {...}, customer: {...}, session: { access_token: 'eyJ...<redacted>.signature' } }

// Hold stock during a long checkout (optional; expires automatically)
const hold = await server.orders.reserveStock({
  requestBody: { items: [{ variant_id: 'e98631a9-...', quantity: 2 }], ttl_seconds: 600 },
});
// → { reservations: [{ reservation_id, variant_id: 'e98631a9-...', quantity: 2 }], reservation_ids: ['16c3c2dc-...'], expires_in_seconds: 600 }

// Which payment providers + currencies are available for this store
const methods = await storefront.payments.getPaymentMethods();

// Confirm a payment after the provider redirect / webhook (server, sk).
// For Stripe, pass the Checkout Session id (cs_test_...) as the reference.
const result = await server.payments.verifyPayment({ requestBody: { provider: 'stripe', reference: 'cs_test_a1GBZkvLEkbsaotrzgHrtKzWKekeLe1bGzXw2xp6lKzMRZkjNiVMprvqS6' } });
// → { provider: 'stripe', reference: 'cs_test_...', status: 'success', amount: 603.99, currency: 'usd', customer_email: 'john.doe@example.com', payment_intent: 'pi_3ABC...', metadata: {} }

// One review by id, and removing your own review
const { review } = await storefront.reviews.getReview({ id: '11bc03d9-...' });
// → { id: '11bc03d9-...', rating: 5, status: 'approved', customer_name: 'John Doe', verified_purchase: true }

await storefront.reviews.deleteReview({ id: '11bc03d9-...', xAuthToken: token });
// → { success: true, message: 'Review deleted' }

// Messaging reads + edits not in the main flow
const thread = await storefront.messaging.getThread({ id: 'de30ebb3-...', xAuthToken: token });
// → { id: 'de30ebb3-...', subject: 'Question about my order', status: 'active', unread_count_store: 1 }

await storefront.messaging.updateThread({ id: 'de30ebb3-...', xAuthToken: token, requestBody: { status: 'resolved' } });
// → { id: 'de30ebb3-...', status: 'resolved' }

await storefront.messaging.editMessage({ id: 'c423c11e-...', xAuthToken: token, requestBody: { message_content: 'Updated text' } });
// → { message: { id: 'c423c11e-...', is_edited: true, edited_at: '2026-06-20T13:52:41.118+00:00' } }

await storefront.messaging.deleteMessage({ id: 'c423c11e-...', xAuthToken: token });
// → { success: true, message_id: 'c423c11e-...', deleted_at: '2026-06-20T13:53:02.704+00:00' }

// Blog + shoppable lookbooks (commerce-aware CMS)
const { posts } = await storefront.cms.listPosts({ limit: 10 });
// → { posts: [{ id, title: 'The Best Tech Gifts for 2026', slug: 'best-tech-gifts-2026', product_count: 2 }], pagination: {...} }

const post = await storefront.cms.getPost({ slug: 'best-tech-gifts-2026' });
// → { id, title, content: { blocks: [...] }, products: [{ product_id, name }] }

const { lookbooks } = await storefront.cms.listLookbooks({ limit: 10 });
// → { lookbooks: [{ id, title: 'Workspace Essentials', slug: 'workspace-essentials', status: 'published' }] }

const lookbook = await storefront.cms.getLookbook({ slug: 'workspace-essentials' });
// → { id, title, collection_id: null, images: [{ url, hotspots: [] }] }

// Newsletter signup capture (email-keyed, idempotent — re-subscribing is safe)
const sub = await storefront.cms.subscribeNewsletter({ requestBody: { email: 'shopper@example.com', source: 'footer' } });
// → { subscribed: true, already_subscribed: false }

// Gift cards: check a balance, or list the customer's cards
const giftCard = await storefront.giftCards.checkGiftCard({ code: 'GTSA-1B2C-3D4E-5F6G' });
// → { code: 'GTSA-1B2C-3D4E-5F6G', balance: 50, currency: 'USD', status: 'active' }

const { gift_cards } = await storefront.giftCards.listGiftCards({ xAuthToken: token, customerId });
// → { gift_cards: [{ code: 'GTSA-...', balance: 50, status: 'active' }] }  (empty array if none)

// One return's detail, and escalating a pending credit offer to a cash refund
const { data: ret } = await storefront.returns.getReturn({ id: '75eef130-...', xAuthToken: token });
// → { id: '75eef130-...', status: 'pending', reason_code: 'damaged', credit_offer: { status: 'none', amount: null } }

const { data: refund } = await storefront.returns.requestReturnRefund({ id: '75eef130-...', xAuthToken: token });
// → { status: 'refund_requested' }

// Record a browsing signal (feeds next-item recommendations) — pk, fire-and-forget
await storefront.events.recordEvent({
  requestBody: { event_type: 'view', variant_id: 'e98631a9-...', session_id: sessionId },
});
// → 202 { recorded: true }

// First-party analytics collector (write-only) — pk
await storefront.analytics.collectAnalyticsEvent({
  requestBody: { event_type: 'page_view', path: '/products/samsung-galaxy-watch-6', session_id: sessionId },
});
// → 202 { recorded: true }

// The store's configured delivery zones (polygon + distance tiers)
const { zones } = await storefront.shipping.getShippingZones();
// → { zones: [{ name: 'Local (within 10 km)', type: 'distance_tier', fee: 5.99 }], total: 4 }

// API metadata (no key) — version, docs, available endpoint prefixes
const info = await storefront.system.getApiInfo();
// → { name: 'Galactic Core API', version: 'v1', documentation: 'https://docs.tybritelabs.com', endpoints: [...] }

// Liveness probe (no key)
const health = await storefront.system.healthCheck();
// → { status: 'ok', timestamp: '2026-06-20T14:00:00.000Z' }

// The full store profile: currency, features, taxonomy, payment + shipping config
const store = await storefront.system.getStoreInfo();
// → { store: { name: 'Galactic Test Store', default_currency: 'USD', timezone: 'America/New_York' }, features: { multi_currency: true, returns: true } }

// Editorial collections curated by the marketplace operator
const { collections } = await operator.marketplace.listMarketplaceCollections();
// → { collections: [{ id, title: 'Holiday Picks', merchant_count: 6 }] }

const collection = await operator.marketplace.getMarketplaceCollection({ id: 'mc_...' });
// → { id, title: 'Holiday Picks', products: [{ product_id, merchant_store_name }] }

// Sponsored placements (marketplace ads)
const slot = await operator.marketplace.getAdSlot({ placement: 'home_hero', context: 'electronics' });
// → { slot: 'home_hero', context: 'electronics', placements: [{ ad_id, product_id, image_url, merchant_store_id }] }

await operator.marketplace.logAdEvent({ requestBody: { ad_id: 'ad_...', event_type: 'click', session_id: sessionId } });
// → 202 { recorded: true, billable: true }

// Validate an authorization request (public; returns the client + the echoed request, never an open redirect)
const authz = await server.gcConnect.getConnectAuthorize({ clientId: 'anvil', redirectUri: 'https://yourapp.com/callback', scope: 'read orders:read', state: 'a8f3...' });
// → { valid: true, client: { client_id: 'anvil', name: 'Anvil', description: '...', logo_url: '...' },
//     request: { redirect_uri: 'https://yourapp.com/callback', scopes: ['read', 'orders:read'], state: 'a8f3...', environment: 'sandbox' } }

// Exchange a one-time code for the sk + pk key pair (the tool's server). Requires the
// app's client_secret; only completes after the merchant approves on the consent page.
const token = await server.gcConnect.connectToken({ requestBody: { client_id: 'anvil', client_secret: '<your secret>', code: '<one-time>', redirect_uri: 'https://yourapp.com/callback' } });
// → { sk: 'tybrite_sk_live_<redacted>', pk: 'tybrite_pk_live_<redacted>', pair_id: '550e8400-...', store_id: '660f9511-...', environment: 'production', scopes: ['read', 'orders:read'], client_id: 'anvil' }

// List a store's active tool connections (sk)
const { sessions } = await server.gcConnect.listConnectSessions();
// → { sessions: [{ pair_id, client_id: 'anvil', created_at, revoked_at: null }] }

// Approve an authorization (called by the in-browser merchant-consent page) → issues a one-time code
const approved = await server.gcConnect.postConnectAuthorize({
  requestBody: { client_id: 'anvil', redirect_uri: 'https://yourapp.com/callback', scope: 'read orders:read', state: 'a8f3...', approve: true },
});
// → { redirect_to: 'https://yourapp.com/callback?code=<one-time>&state=a8f3...' }

// Disconnect a tool (the tool or merchant revokes the key pair)
const revoked = await server.gcConnect.connectRevoke({
  requestBody: { pair_id: '550e8400-...', client_id: 'anvil', client_secret: 'YOUR_CLIENT_SECRET' },
});
// → { success: true }   (or { success: true, message: 'Already revoked' })

// One delivered event with its delivery attempts
const event = await server.webhooks.getWebhookEvent({ id: 'evt_1781955476025_lp1jafe' });
// → { id: 'evt_1781955476025_lp1jafe', type: 'order.created', payload: { livemode: true, data: { object: {...} } }, environment: 'production' }

// Remove an endpoint
await server.webhooks.deleteWebhookEndpoint({ id: 'ac6737d6-12b9-446d-a6c4-1077493f498f' });
// → { success: true, message: 'Webhook endpoint deleted' }