Advanced Checkout Guide

mkdir firmly-quickstart && cd firmly-quickstart
npm init -y
npm install jose

// agent.mjs — Minimal flow that places a real Firmly order.
// Usage: FIRMLY_APP_ID=... node agent.mjs

import { CompactEncrypt, importJWK } from 'jose';
import { randomUUID } from 'node:crypto';

const APP_ID   = process.env.FIRMLY_APP_ID   || 'YOUR_APP_ID';
const DOMAIN   = process.env.FIRMLY_DOMAIN   || 'staging.luma.gift';
if (APP_ID === 'YOUR_APP_ID') throw new Error('Set FIRMLY_APP_ID to your sandbox App ID first (request one from Firmly): FIRMLY_APP_ID=<uuid> node agent.mjs');
const API      = 'https://api.firmly.work';
const PAY_API  = 'https://cc.firmly.work';
// Some HTTP clients' default User-Agent is blocked by sandbox bot-protection (403).
// A browser-style UA passes — set one on every call.
const UA       = 'Mozilla/5.0 (compatible; firmly-quickstart)';

// A test shipping address. Same address is used for billing.
const ADDRESS = {
  first_name: 'Test',  last_name: 'Buyer',
  email: 'test@example.com',
  phone: '+15551234567',
  address1: '500 Howard St',
  city: 'San Francisco',
  state_or_province: 'CA',
  country: 'US',
  postal_code: '94105'
};

// A sandbox-safe test card. Only works against test merchants.
const TEST_CARD = {
  number: '4111111111111111',
  name: 'Test Buyer',
  verification_value: '123',
  month: '12',
  year: '2030'
};

// 1. Bootstrap a browser session (returns a JWT)
const session = await fetch(`${API}/api/v1/browser-session`, {
  method: 'POST',
  headers: { 'x-firmly-app-id': APP_ID, 'User-Agent': UA }
}).then(r => r.json());

const TOKEN = session.access_token;
const auth  = {
  'x-firmly-authorization': TOKEN,
  'Content-Type': 'application/json',
  'User-Agent': UA
};

// 2. Discover — search the catalog
const search = await fetch(
  `${API}/api/v1/discovery/search`,
  {
    method: 'POST',
    headers: auth,
    // discovery/search spans every merchant — scope it to this store with filters.domains
    body: JSON.stringify({ query: 'bag', filters: { domains: [DOMAIN] }, page_size: 5 })
  }
).then(r => r.json());

// Take the first product and its first *available* variant
const product = search.products?.find(p => p.domain === DOMAIN);
if (!product) throw new Error(`No products matched at ${DOMAIN}`);

const variant = product.variants?.find(v => v.available) || product.variants?.[0];
const addRef  = variant.add_to_cart_ref;

// 3. Add to cart
await fetch(
  `${API}/api/v2/domains/${DOMAIN}/cart/line-items`,
  {
    method: 'POST',
    headers: auth,
    body: JSON.stringify({ add_to_cart_ref: addRef, quantity: 1 })
  }
);

// 4. Set shipping address
const shipped = await fetch(
  `${API}/api/v2/domains/${DOMAIN}/cart/shipping-info`,
  { method: 'POST', headers: auth, body: JSON.stringify(ADDRESS) }
).then(r => r.json());

const shipmentId = shipped.shipments?.[0]?.shipment_id;

// 5. Pick the cheapest shipping method.
//    Methods are populated inline on the shipment by set-shipping-info —
//    read them from shipping_method_options (get-availability returns
//    delivery dates / slots, not methods).
//    See api-reference/shipment-configuration/shipping-and-fulfillment.
const methods = shipped.shipments?.[0]?.shipping_method_options || [];
const cheapest = methods.slice().sort((a, b) => a.price.value - b.price.value)[0];

// 6. Set the chosen shipping method
await fetch(
  `${API}/api/v2/domains/${DOMAIN}/cart/shipment/methods`,
  {
    method: 'POST', headers: auth,
    body: JSON.stringify({
      shipment_id: shipmentId,
      shipping_method_id: cheapest.id
    })
  }
);

// 7. Get the payment public key
const jwk = await fetch(`${PAY_API}/api/v1/payment/key?format=JWK`, { headers: { 'User-Agent': UA } }).then(r => r.json());

// 8. JWE-encrypt the card
const publicKey = await importJWK(jwk, 'RSA-OAEP-256');
const encryptedCard = await new CompactEncrypt(
  new TextEncoder().encode(JSON.stringify(TEST_CARD))
)
  .setProtectedHeader({ alg: 'RSA-OAEP-256', enc: 'A256GCM', kid: jwk.kid })
  .encrypt(publicKey);

// 9. Complete the order.
//    The cart was built over steps 3–6 (line item, shipping address, shipping
//    method), so complete-order finalizes that EXISTING cart — the body carries
//    only encrypted_card + billing_info. place-order is the one-shot alternative:
//    it creates the cart AND places the order in a single call, taking an items[]
//    array plus shipping_info instead. See the API reference for both.
const order = await fetch(
  `${PAY_API}/api/v2/payment/domains/${DOMAIN}/complete-order`,
  {
    method: 'POST',
    headers: {
      ...auth,
      'Idempotency-Key': randomUUID()
    },
    body: JSON.stringify({
      encrypted_card: encryptedCard,
      billing_info:   ADDRESS
    })
  }
).then(r => r.json());

console.log('Status:', order.cart_status);                       // "submitted" on success
console.log('Cart ID:', order.cart_id);                          // Firmly's internal reference
console.log('Confirmation URL:', order.urls?.thank_you_page);    // merchant's confirmation page
console.log('Merchant ref:', order.platform_order_number);       // merchant's order number
console.log('Total:', order.total?.symbol + order.total?.value);  // value = decimal price; number is smallest-unit (cents)

FIRMLY_APP_ID=your_sandbox_app_id node agent.mjs