Live Rate Providers

A live rate provider is an HTTP endpoint your app exposes that the platform calls at checkout to fetch live shipping rates from your carrier. Rates you return render alongside the merchant’s own shipping zones — the customer picks one with a normal radio button, and your app’s chosen carrier identity follows the order through placement, webhook, and fulfillment write-back. Apps register a callback URL in their manifest, return rates on demand, and receive orders/create webhooks where they recognise their own picked rates and act on them. Common implementations include domestic and cross-border courier integrations.

For rate logic that doesn’t need a remote carrier API — e.g. a fixed surcharge above a cart-value threshold — use a shipping_rate Function instead. Functions run server-side in our sandbox; live rate providers run on your infrastructure.

The Flow

1. Declare in your app manifest

Add a liveRateProviders[] entry to your app.json. The endpoint template ${APP_URL} is substituted with the value the merchant configured at install time.

app.json

{
  "handle": "acme-shipping",
  "name": "Acme Shipping",
  "scopes": [
    "read_orders",
    "write_orders",
    "read_metafields",
    "write_metafields"
  ],
  "extensions": {
    "liveRateProviders": [
      {
        "handle": "acme-rates",
        "endpoint": "${APP_URL}/api/quote",
        "timeoutMs": 5000,
        "description": "Live rates from Acme's carrier API."
      }
    ],
    "webhooks": [
      {
        "topic": "orders/create",
        "endpoint": "${APP_URL}/api/order-create"
      }
    ]
  }
}

Field	Required	Notes
`handle`	yes	Provider handle within your app. Multiple providers per app allowed (e.g. domestic + international).
`endpoint`	yes	URL the dispatcher POSTs to. Template `${APP_URL}` resolves to your app’s base URL.
`timeoutMs`	optional	Hard cap. Defaults to 5s, max 9s. Slow providers fail open — checkout never breaks.
`description`	optional	Shown in the merchant’s installed-apps admin.

2. Build the `/quote` endpoint

The dispatcher POSTs a Carrier-Service-shaped body, HMAC-signed with your app’s clientSecret over the raw bytes:

POST /api/quote HTTP/1.1
Content-Type:      application/json
X-LMS-Signature:   <hex(HMAC-SHA256(rawBody, clientSecret))>
X-LMS-RequestId:   d3b8fa2c-...

Request body:

{
  "rate": {
    "origin": {},
    "destination": {
      "country":     "IN",
      "country_code": "IN",
      "city":        "Mumbai",
      "province":    "MH",
      "postal_code": "400001",
      "zip":         "400001",
      "cod":         false
    },
    "items": [
      {
        "variant_id": "var_...",
        "product_id": "prod_...",
        "sku":        "ABC-MED",
        "quantity":   1,
        "grams":      1500,
        "price":      499,
        "title":      "Slipper M"
      }
    ],
    "currency": "INR",
    "locale":   "en"
  },
  "shop": {
    "domainSlug": "acme-store",
    "storeId":    "ef10744c-5c4a-4f47-85fc-062ba44afb5f",
    "name":       "Acme Store",
    "url":        "acme-store.launchmystore.io"
  },
  "request_id": "d3b8fa2c-..."
}

rate.origin is currently always {} — quote from the warehouse address the merchant configured in your app’s settings (as the reference apps do), not from the request.

Verify the signature, look up the merchant’s per-shop credentials from your data store, then call your carrier and return rates.

Key your per-merchant storage on shop.storeId — it is the immutable merchant identifier. shop.domainSlug changes when a merchant moves to a custom domain, and apps keyed on it lose every merchant that upgrades their domain. (Session tokens carry the same id as storeId/sub.)

Response body (total_price is in minor units — "8085" is ₹80.85):

{
  "rates": [
    {
      "service_name": "Blue Dart Air",
      "service_code": "acme-1",
      "total_price":  "8085",
      "currency":     "INR",
      "description":  "1 days · Blue Dart Air",
      "min_delivery_date": "2026-06-04T00:00:00Z",
      "max_delivery_date": "2026-06-05T00:00:00Z"
    },
    {
      "service_name": "DTDC Surface",
      "service_code": "acme-12",
      "total_price":  "4250",
      "currency":     "INR",
      "description":  "3 days · DTDC Surface"
    }
  ]
}

Each rate field:

Field	Required	Purpose
`service_name`	yes	Bold title in the picker (e.g. `"Blue Dart Air"`). Becomes the rate’s display name.
`service_code`	yes	Stable, unique per rate identifier within your app. Echoed back on `orders/create`, and used by the platform to server-side re-validate the picked rate’s price at order placement (match order: code → name → exact price). Duplicate or missing codes weaken that validation. Convention: `<app_handle>-<carrier_id>` (e.g. `acme-1`).
`total_price`	yes	String. Minor currency units (paise, cents): `"8085"` renders as ₹80.85. The platform divides by 100 everywhere it displays or persists the amount.
`currency`	yes	ISO-4217, and it must be the currency your amount is actually in. Echo the request’s `rate.currency` when you can quote in it; when your carrier only prices in its own currency (USPS quotes USD, Shiprocket quotes INR), return that currency and the platform converts. See Currency conversion below.
`description`	optional	Secondary line in the picker (`"3-5 days · DDP available"`).
`min_delivery_date` / `max_delivery_date`	optional	ISO-8601. Shown to customers on themes that support delivery-window display.

Currency conversion

The dispatch body asks you to quote in rate.currency (the store’s display currency), but a carrier can only price in the currency it operates in. So the platform normalises every returned rate into the display currency before it reaches checkout, order validation or the persisted order:

currency equals the requested currency → used as-is, no conversion.
currency differs → the amount is converted at the platform’s exchange rate. The original is preserved on the rate as quoted_price / quoted_currency for reconciliation.
No usable exchange rate for that pair → the rate is dropped rather than charged at the wrong number, and a warning is logged.

Because conversion happens once, at the point rates enter the platform, everything downstream sees a single consistent currency and rate fingerprints still match at order-time re-validation.

Never label an amount with the requested currency when it is really in your carrier’s. Doing so was previously undetectable: a ₹104.85 rate returned as currency: "INR" to a LAK-display store was charged as ₭104.85 — off by a factor of ~20,000 — because the platform trusted the label. It now converts on currency, so an honest currency is required for a correct charge.

Fail-open semantics. Any of: timeout, 5xx, malformed JSON, empty array — treated as “no rates from this provider” and the checkout falls back to the merchant’s ShippingZones. Your provider failing is never a customer-facing error.

3. Verify the HMAC

Use the platform’s shared package:

import express from 'express';
import { verifyRateRequest } from '@launchmystore/apps-shared';

app.post('/api/quote', express.raw({ type: 'application/json' }), (req, res) => {
  const ok = verifyRateRequest({
    rawBody: req.body.toString('utf8'),
    header:  req.headers['x-lms-signature'],
    clientSecret: process.env.LMS_CLIENT_SECRET,
  });
  if (!ok) return res.status(401).json({ error: 'Invalid signature' });

  const body = JSON.parse(req.body.toString('utf8'));
  const dest = body.rate?.destination || {};
  const items = body.rate?.items || [];
  // ... call your carrier, return rates
  res.json({ rates: [...] });
});

Or use the all-in-one middleware:

import { carrierServiceMiddleware } from '@launchmystore/apps-shared';

app.post(
  '/api/quote',
  carrierServiceMiddleware({ clientSecret: process.env.LMS_CLIENT_SECRET }),
  async (req, res) => {
    // req.body is already parsed and HMAC-verified.
    res.json({ rates: await myQuoteLogic(req.body) });
  },
);

4. Render-side guarantees

Each rate you return is tagged by the platform before it reaches the storefront with:

{ ...yourRate,
  appId:      "<your app uuid>",
  appHandle:  "acme-shipping",
  appName:    "Acme Shipping",
  source:     "live_rate_provider"
}

The /checkout picker renders every app’s rate with the same template, so your service_name and description appear exactly as you sent them — alongside a small via {Apps.name} label for trust signalling:

○  Blue Dart Air   1 days · via Acme Shipping     ₹80.85
○  DTDC Surface    3 days · via Acme Shipping     ₹42.50
○  <merchant's own ShippingZone>                  ₹100.00

The customer picks one. No code change needed in your app for the display layer — your rate JSON is what the customer sees.

5. Receive the `orders/create` webhook

Subscribe to orders/create in your manifest (see step 1). When the customer places an order, the platform POSTs:

{
  "id":           "abc-123",
  "name":         "#A0XJ12K",
  "order_number": "A0XJ12K",
  "email":        "buyer@example.com",
  "financial_status": "pending",
  "currency":     "INR",
  "total_price":  "155.85",
  "shipping_address": {
    "address1": "1 MG Road", "city": "New Delhi", "province": "DL",
    "country": "India", "zip": "110011", "phone": "9876543210"
  },
  "line_items": [
    { "id": "...", "product_id": "...", "variant_id": "...",
      "title": "Slipper M", "quantity": 1, "price": "75.00" }
  ],
  "shipping_lines": [
    {
      "title":    "Blue Dart Air",
      "code":     "acme-1",
      "source":   "acme-shipping",
      "price":    "80.85",
      "currency": "INR"
    }
  ]
}

The body is the order in standard commerce shape — there is no { order, orderProducts, shop } wrapper. The sending store is the X-LMS-Shop-Domain request header, and shipping_lines[] (carrying your routing source) is preserved at the top level.

The shipping_lines[] array is the routing key. Your handler must inspect shipping_lines[].source and only act when it matches your app handle:

import {
  createFulfillment,
} from '@launchmystore/apps-shared';

app.post('/api/order-create', async (req, res) => {
  const order = req.body;                       // the body IS the order
  const shopDomain = req.headers['x-lms-shop-domain'];
  const APP_HANDLE = 'acme-shipping';

  const myLine = (order.shipping_lines || []).find((l) => l.source === APP_HANDLE);
  if (!myLine) {
    // Customer picked someone else's rate (or a merchant zone). Skip.
    return res.json({ ok: true, skipped: 'not-my-rate' });
  }

  // Strip the app prefix to recover your carrier's courier id.
  const myCarrierId = Number(String(myLine.code).replace(/^acme-/, ''));

  // Look up the merchant's per-shop credentials.
  const creds = await loadCreds(shopDomain);

  // Translate to your carrier's API.
  const { awb, courier_name } = await callMyCarrierCreateShipment({
    creds,
    order,
    lineItems: order.line_items,
    courier_id: myCarrierId,
  });

  // Write back the AWB so the platform's Order shows tracking
  // and Order.status flips to 'shipped'.
  await createFulfillment({
    accessToken: await getOAuthTokenFor(shopDomain),
    orderId: order.id,
    trackingNumber:  awb,
    trackingCompany: courier_name,
    trackingUrl:     `https://acme.example/track/${awb}`,
    status:          'success',
  });

  res.json({ ok: true, awb });
});

Why source-based routing matters. If a merchant installs BOTH your app and a competitor app, both apps receive the same orders/create webhook. Without the source check, both apps would race to push shipments. Inspecting shipping_lines[].source === APP_HANDLE is the contract that makes installed-apps coexist.

Native local pickup is handled by the same source check. When a merchant enables in-store pickup on a warehouse (no app required), and the customer chooses the Pickup tab at checkout, the order’s shipping_lines[].source is "local_pickup" — never your app handle. So the find((l) => l.source === APP_HANDLE) guard above already skips these orders correctly; you don’t need any extra branch (the pickup line’s source is "local_pickup", never your app handle).

6. Optional auto-push without customer pick

If the merchant has auto_push_enabled set in your config metafield AND shipping_lines[].source is null (= the customer picked a merchant zone, not your rate), you can still push if your app handles ALL of the merchant’s shipping. This is what Flow B looks like. The shipped Shiprocket app in the repo demonstrates both modes — see shiprocket/src/server.js /api/order-create for the source-match + auto-push patterns.

7. Storing merchant credentials

Apps often store per-merchant carrier credentials in shop metafields to stay database-free. Shop metafields are not private: themes can render {{ shop.metafields.your_namespace.api_password }} and other installed apps with read_metafields can list them. Never store credentials in plaintext — seal them first:

import { sealSecret, openSecret } from '@launchmystore/apps-shared';

// write
await setValue({ ..., key: 'api_password',
  value: sealSecret(password, process.env.LMS_CLIENT_SECRET) });

// read
const password = openSecret(stored, process.env.LMS_CLIENT_SECRET);

sealSecret is AES-256-GCM keyed off your clientSecret (enc:v1:... wire format); openSecret passes legacy plaintext through unchanged and returns null on tamper.

7. Cache, retries, idempotency

Concern	Platform behaviour	Your app’s responsibility
Quote cache	10 minutes for non-empty results; ~30 seconds for empty results (so a transient outage doesn’t hide your rates), keyed on `storeId + destination + items fingerprint`	None
Quote retry	3 retries on 5xx / network errors with 250/500/1000 ms backoff. Timeouts are NOT retried — a request that hits your `timeoutMs` fails open immediately	Be idempotent (same request → same rates), answer fast
Webhook delivery	3 retries with exponential backoff: 1m / 5m / 15m	Return 2xx within 10s, or the dispatcher retries
Webhook signature	`X-LMS-Hmac-SHA256: base64(HMAC-SHA256(rawBody, webhookSecret))` — note this differs from the quote endpoint’s `X-LMS-Signature` (hex, clientSecret)	Verify before processing
Webhook idempotency	Delivery is at-least-once (`X-LMS-Webhook-Id` identifies a delivery; retries re-send it)	Check your own shipment record for the order id before creating a carrier shipment — e.g. store a `shipment` metafield on the order and skip when it exists. A retry after a slow-but-successful push must not create a second billable shipment

8. Multi-package support

You can split a single order across multiple shipments. Each call to createFulfillment with a different line_items subset becomes a new Fulfillment row + tracking entry on the order. Order.status flips to partial until coverage hits 100%, then shipped. See Create Fulfillment for the exact body shape and multi-package examples.

Reference

Fulfillment Services — registering as a tracking provider
Create Fulfillment — pushing the AWB back
orders/create webhook payload — full body schema with shipping_lines[]
shipping_rate Function — for rates that don’t need a remote carrier
Build a shipping app — end-to-end guide

Get Started

Guides

Extensions

Functions

App Bridge

Billing

AI & MCP

Live Rate Providers

Live Rate Providers

The Flow

1. Declare in your app manifest

2. Build the `/quote` endpoint

Currency conversion

3. Verify the HMAC

4. Render-side guarantees

5. Receive the `orders/create` webhook

6. Optional auto-push without customer pick

7. Storing merchant credentials

7. Cache, retries, idempotency

8. Multi-package support

Reference

​Live Rate Providers

​The Flow

​1. Declare in your app manifest

​2. Build the /quote endpoint

​Currency conversion

​3. Verify the HMAC

​4. Render-side guarantees

​5. Receive the orders/create webhook

​6. Optional auto-push without customer pick

​7. Storing merchant credentials

​7. Cache, retries, idempotency

​8. Multi-package support

​Reference

Live Rate Providers

The Flow

1. Declare in your app manifest

2. Build the `/quote` endpoint

Currency conversion

3. Verify the HMAC

4. Render-side guarantees

5. Receive the `orders/create` webhook

6. Optional auto-push without customer pick

7. Storing merchant credentials

7. Cache, retries, idempotency

8. Multi-package support

Reference