docs
/
Client Integration

Quickstart

Run a server-side application exchange, list products, and calculate a controlled cart with native fetch.

This exercise uses Node 20+ with native fetch, a configured AppEngine organization, application credentials, and an existing sellable SKU. It reads a catalog and calculates a cart. Calculation can create an sf_cart record; use a development organization. It does not charge a provider or place an order.

1. Set server configuration

Create a private .env.local file, excluded from version control:

APPENGINE_ENDPOINT=https://appengine.appmint.io
ORG_ID=your-org-id
APP_ID=your-app-id
APP_KEY=your-app-key
APP_SECRET=your-app-secret
TEST_SKU=your-existing-sku

Use the endpoint assigned to your deployment. Do not prefix credentials with NEXT_PUBLIC_ or VITE_. These examples are server scripts, not browser JavaScript.

The secret belongs on a server like this one. A phone app does not ship it; it signs in with Apple App Attest or Google Play Integrity instead — see Phone apps without a secret.

2. Save and run the request

Create quickstart.mjs:

const required = (key) => {
  const value = process.env[key];
  if (!value) throw new Error(`Missing ${key}`);
  return value;
};
const host = required('APPENGINE_ENDPOINT').replace(/\/+$/, '');
const orgid = required('ORG_ID');

async function read(response) {
  const text = await response.text();
  let body;
  try { body = text ? JSON.parse(text) : undefined; } catch { body = text; }
  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${body?.code ?? body?.error ?? body?.message ?? response.statusText}`);
  }
  return body;
}
const auth = await read(await fetch(`${host}/profile/app/key`, {
  method: 'POST',
  headers: { orgid, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    appId: required('APP_ID'), key: required('APP_KEY'), secret: required('APP_SECRET'),
  }),
  signal: AbortSignal.timeout(15_000),
}));
if (!auth?.token) throw new Error('Application exchange returned no token');

async function request(path, body) {
  return read(await fetch(`${host}/${path}`, {
    method: body === undefined ? 'GET' : 'POST',
    headers: {
      orgid, Authorization: `Bearer ${auth.token}`,
      ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),
    },
    body: body === undefined ? undefined : JSON.stringify(body),
    signal: AbortSignal.timeout(15_000),
  }));
}

const page = await request('storefront/products?p=1&ps=5');
if (!Array.isArray(page?.data)) throw new Error('Expected paged product records');
console.log('Catalog', { page: page.page, count: page.data.length, hasNext: page.hasNext });

const product = await request(`storefront/product/${encodeURIComponent(required('TEST_SKU'))}`);
if (!product?.data?.sku) throw new Error('Test product not found');
const quote = await request('storefront/pricing/calculate-cart', {
  productItems: [{ sku: product.data.sku, quantity: 1, itemType: 'product' }],
  shippingAddress: {
    street1: '1 Main St', city: 'Dallas', state: 'TX', zip: '75001', country: 'US',
  },
});
if (!Number.isFinite(quote?.total)) throw new Error('No usable total');
console.log('Quote', {
  cartId: quote.cartId, total: quote.total, tax: quote.tax,
  shipping: quote.productShipping, valid: quote.valid,
});
node --env-file=.env.local quickstart.mjs

Expected result: a catalog count and a quote with your organization's values. An empty catalog is a valid response if there are no matching products; it is different from a request error. No particular product, price, shipping rate, or tax amount is seeded by this guide.

3. Understand the response

storefront/products returns a paged object with data, page, pageSize, total, and hasNext. Each row has platform fields such as sk, pk, and datatype; product fields are inside row.data. A product detail response is one record. Display data.calculatedPrice.finalPrice when available, with list price as a display fallback.

Pricing returns a summary at the top level. Render total as sent; it already includes the returned tax and shipping. Send items, destination, and coupon together. valid: false is a coupon verdict that can arrive in a successful HTTP response; inspect reason and message. An unquotable destination or failed product resolution needs handling separately. The current pricing service can fall back on input prices after a line lookup failure, so a 200 alone is not a sellability or payment guarantee.

4. Add customer ownership separately

A catalog request can work without a customer. Customer profile, saved cart, and order history need the customer's session. Your server must exchange customer credentials, handle any verification challenge, store a session, and forward the token as x-client-authorization alongside its own app token. Follow Authentication; do not turn the application identity into the buyer.

Use GET client-data/profile, GET storefront/cart/mine, and GET client-data/orders for customer readback. A null saved cart means no saved cart; a 401 means the request lacks a usable customer session. Checkout is a separate operation requiring a persisted, reconciled cart, explicit buyer, delivery decisions, and the selected payment flow. The examples do not implement checkout.

Diagnose the first failure

ResultCheck
Missing environment errorFile path, variable names, and server startup environment
App exchange fails or has no tokenApplication registration, organization, secret, and deployment endpoint. 401 with reason: "secret_refused" means the app credential's check is set to Enforce; give the server its own app credential with the check Off
HTTP 400 / missing_orgidTrusted tenant header is present
HTTP 401 after app exchangeCustomer requirement versus application authentication; preserve both identities
HTTP 403The caller's role/permission; do not retry as a different user
Product detail missingActual SKU/slug and visibility in the intended organization
Quote exists but destination cannot be servedShipping configuration, address, and shipping/options result
Network failureConnectivity/timeout; do not replace the failed result with an empty catalog

Continue with the TypeScript SDK, Next.js example, or Remix example.