Documentation Index

Fetch the complete documentation index at: https://docs.launchmystore.io/llms.txt

Use this file to discover all available pages before exploring further.

​

Network access

​

When to use it

• You need a real-time lookup that the merchant can’t pre-compute (live currency rate, live tax table, stock at a 3PL).
• You’re integrating with an external service whose data isn’t appropriate to mirror into metafields (fraud score, loyalty tier, carrier rate).
• You need to side-effect to your own backend (write an analytics event when a function fires — though prefer the host’s audit log when possible).

​

Manifest

{
  "handle": "loyalty-bonus",
  "name": "Loyalty Bonus",
  "version": "1.0.0",
  "extensions": {
    "functions": [
      {
        "type": "discount",
        "handle": "loyalty-tier-bonus",
        "entrypoint": "dist/loyalty.wasm",
        "network_access": true,
        "allowed_hosts": [
          "api.loyalty.example.com",
          "edge.loyalty.example.com"
        ]
      }
    ]
  }
}

​

Field reference

​

Install-time validation

HTTP/1.1 400 Bad Request
{ "error": "Invalid function manifest for \"loyalty-tier-bonus\": allowed_hosts entry \"https://api.loyalty.example.com\" is not a valid hostname" }

​

Runtime API

lms_host.fetch_url(urlPtr, urlLen, optsPtr, optsLen) -> int32

export default async function main(input) {
  const customer = input.customer;
  if (!customer?.id) return { discounts: [] };

  // (Once the runtime shim is wired.)
  const r = await fetch(
    `https://api.loyalty.example.com/customers/${customer.id}/tier`,
  );
  if (!r.ok) return { discounts: [] };

  const { tier } = await r.json();
  if (tier !== 'platinum') return { discounts: [] };

  return {
    discounts: [
      { title: 'Platinum loyalty bonus', value: 15, valueType: 'percentage', target: 'order', targetSelection: 'all' },
    ],
  };
}

​

Limits

​

Return codes

​

Dispatch behaviour when a fetch is blocked

const r = await fetch('https://api.loyalty.example.com/tier');
if (!r.ok || r.status >= 500) {
  // Fail open: skip the bonus, don't break the cart.
  return { discounts: [] };
}

async function fetchWithRetry(url, retries = 1) {
  for (let i = 0; i <= retries; i++) {
    const r = await fetch(url);
    if (r.ok) return r;
    if (r.status < 500) return r; // 4xx — don't retry
  }
  return null;
}

​

TLS / CORS notes

• TLS is required. The runtime only allows https:// URLs even if the host is in allowed_hosts. There is no plaintext escape hatch.
• No CORS. The host import is a server-to-server fetch initiated by the WASM worker process — there is no browser, no preflight, no Access-Control-Allow-Origin to consider. Your endpoint can be locked down to Origin: lms-functions.launchmystore.io if you need to verify the caller.
• No cookies. The runtime doesn’t carry merchant/customer cookies on outbound calls. Authenticate with an API key or Bearer token your app already has.
• No streaming. Response bodies are fully buffered (capped at 64 KB) before the function sees them. There is no ReadableStream.

​

Authenticating outbound calls

1. Bake a key into the WASM bundle. Simplest for first-party apps — the key sits in your compiled module and lands on the merchant’s disk only as part of your signed bundle. Risk: anyone who pulls the WASM apart can read the key.
2. Embed the key in a merchant-specific app metafield that the function reads from cart.metafields.app_<handle>.api_key.value. The merchant can rotate the key independently of the function binary.

​

Observability

{
  "networkAccess": true,
  "outboundCalls": [
    { "host": "api.loyalty.example.com", "status": 200, "bytes": 482, "ms": 134 },
    { "host": "api.loyalty.example.com", "status": 502, "bytes": 0,   "ms": 1502, "errorCode": -4 }
  ]
}

• Calls per function per day — to track usage.
• p50 / p95 outbound latency — to spot slowness before it shows up as checkout latency.
• Failure rate by error code — to catch new -3 host-allowlist errors after a deploy.

​

Common patterns

​

Real-time rate API

// type: shipping_rate
export default async function main(input) {
  const r = await fetch(
    `https://rates.carrier.example.com/quote?zip=${input.destination.zip}&weight=${cartWeight(input.cart)}`,
    { headers: { 'X-Api-Key': API_KEY } },
  );
  if (!r.ok) {
    // Fail open with a default rate so the cart doesn't break.
    return { rates: [{ name: 'Standard', price: 9.99 }] };
  }
  const { rates } = await r.json();
  return { rates };
}

​

Geo-IP / fraud check

// type: order_validation
export default async function main(input) {
  const r = await fetch(
    `https://fraud.example.com/score?country=${input.shippingAddress.country}&total=${input.cart.totalPrice}`,
  );
  if (!r.ok) return { errors: [] }; // fail open

  const { score, reason } = await r.json();
  if (score > 0.9) {
    return {
      errors: [
        { message: `Order flagged for review: ${reason}`, target: 'cart' },
      ],
    };
  }
  return { errors: [] };
}

​

Loyalty tier lookup

// type: discount
export default async function main(input) {
  const id = input.customer?.id;
  if (!id) return { discounts: [] };

  const r = await fetch(
    `https://api.loyalty.example.com/customers/${id}/tier`,
    { headers: { 'Authorization': `Bearer ${API_KEY}` } },
  );
  if (!r.ok) return { discounts: [] };

  const { tier } = await r.json();
  const rate = { gold: 5, platinum: 10, diamond: 15 }[tier] || 0;
  if (rate === 0) return { discounts: [] };

  return {
    discounts: [{
      title: `${tier} loyalty (${rate}%)`,
      value: rate,
      valueType: 'percentage',
      target: 'order',
      targetSelection: 'all',
    }],
  };
}

​

Security considerations

• allowed_hosts is an allowlist, not a regex. Every host you want to reach must be enumerated by exact match. This is intentional — a regex allows escalation by typo, an allowlist doesn’t.
• Don’t include localhost or private IP ranges. The validator rejects single-label hosts and IPs, and the runtime additionally refuses RFC1918 ranges and link-local addresses even if you somehow declared them. The platform does not let WASM functions probe the internal network.
• Treat your endpoint as untrusted-input territory. Anyone who can install your app on a merchant can trigger calls to your allowed hosts. Rate-limit by API key, log every call, and refuse requests with suspicious payloads.
• Cache aggressively on your side. Returning a cached response for the same (customer, cart) tuple keeps your function fast and your upstream costs predictable.
• Rotate API keys regularly. Use the metafield-based pattern (see Authenticating outbound calls) so rotation doesn’t require a WASM rebuild.

​

Best practices

• Short timeouts on your side too. Your endpoint should fail in <500 ms 99% of the time. The platform’s 1500 ms hard timeout is a safety net, not a target.
• Return structured errors. A 200 with { "ok": false, "reason": ... } is faster than a 5xx because the runtime doesn’t have to retry.
• Cache aggressively. Each verifyCart and addClientOrder can trigger function dispatch — if your endpoint is slow or rate-limited you’ll cause cart latency that shows up in conversion metrics.
• Keep allow-lists tight. A single misconfigured host can leak data if your function reads sensitive merchandise attributes.
• Decide fail-open vs fail-closed deliberately. On -4 (timeout), decide whether your function should return a no-op output (fail open — preserve cart usability) or surface an error (fail closed — block the bad state). Most discount/shipping functions should fail open; order-validation and fulfillment-constraints functions might fail closed.
• Log the request id. Pass the cart.id or customer.id as a header so your upstream logs can be correlated with the function run in the developer portal.

​

See also

• Input field selection — the other manifest-level field that shapes function runtime behaviour.
• Discount functions, Shipping rate functions, Order validation — common consumers of network access.
• App metafields — for storing per-merchant API keys outside the WASM bundle.