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.
Video tutorials for this topic
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-skuUse 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.mjsExpected 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
| Result | Check |
|---|---|
| Missing environment error | File path, variable names, and server startup environment |
| App exchange fails or has no token | Application 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_orgid | Trusted tenant header is present |
| HTTP 401 after app exchange | Customer requirement versus application authentication; preserve both identities |
| HTTP 403 | The caller's role/permission; do not retry as a different user |
| Product detail missing | Actual SKU/slug and visibility in the intended organization |
| Quote exists but destination cannot be served | Shipping configuration, address, and shipping/options result |
| Network failure | Connectivity/timeout; do not replace the failed result with an empty catalog |
Continue with the TypeScript SDK, Next.js example, or Remix example.
