Build a shipping app

This guide walks through the complete contract a shipping app honours end-to-end — install handoff, quoting live rates at checkout, fulfillment service registration, receiving the orders/create webhook with shipping_lines[], pushing to your carrier API, and writing tracking back so order.status auto-advances. If you’re building a real-world shipping integration (Shiprocket-style domestic, or a cross-border courier), this is the full surface.

The full chain

The platform implements a Carrier-Service-equivalent contract: live quotes at checkout, orders/create webhook with carrier identity on shipping_lines[].source/code, and a back-pushed fulfillment that flips order status. Every step below is wired the same way for every shipping app — Shiprocket, ShipGlobal, or your own.

Architecture at a glance

┌──────────────┐    OAuth     ┌────────────────┐    POST tracking    ┌──────────────┐
│ Your app     │ ──────────►  │  Platform      │ ◄─────────────────  │ Your app     │
│ (your infra) │              │  /api/v1       │                     │ post-AWB     │
└──────┬───────┘              └────────┬───────┘                     └──────┬───────┘
       │                               │                                    │
       │ /auth handoff                 │ writes order.fulfillments[]       │
       │ POST fulfillment_services.json│ flips order.status                │
       │                               │                                    │
       ▼                               ▼                                    ▼
   serviceId                   fulfillments[] array                Admin order page
   cached in metafields        on the order                        renders package
                                                                   card per shipment

1. OAuth install handoff

After the merchant clicks Install in the app store, the platform redirects to your app’s /auth URL with an HMAC-signed querystring. See Install handoff for the full HMAC verification recipe. Inside your /auth handler, exchange the authorization code for an access token by POSTing to the OAuth token endpoint:

const res = await fetch('https://api.launchmystore.io/apps/oauth/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    grant_type: 'authorization_code',
    client_id: CLIENT_ID,
    client_secret: CLIENT_SECRET,
    code: req.query.code,
    state: req.query.state,
    // code_verifier: ... // include if you used PKCE on /authorize
  }),
});
const result = await res.json();
// result.data = { access_token, refresh_token, token_type: 'bearer', expires_in }
const token = result.data;

Responses use the platform envelope { status, state, message, data } — the token pair lives under data. Cache access_token keyed by storeId; every API call below sends it as the Authorization: Bearer header. When it expires, POST the same endpoint again with grant_type=refresh_token and your refresh_token.

2. Register as a fulfillment service

In the same /auth handler, register your app as a fulfillment service so the platform knows tracking is supported and attributes shipments back to your app. This is idempotent — safe to call on every install or reinstall. First check whether you’ve already registered (so reinstalls don’t create duplicates), then create the service if it’s missing:

const BASE = 'https://api.launchmystore.io';
const auth = { Authorization: `Bearer ${token.access_token}` };
const json = { 'Content-Type': 'application/json', ...auth };

// 1. Look for an existing service with your name.
const listRes = await fetch(`${BASE}/api/v1/fulfillment_services.json`, {
  headers: auth,
});
const list = (await listRes.json()).data?.fulfillment_services || [];
let service = list.find((s) => s.name === 'Acme Shipping');

// 2. Create it only if it doesn't exist (scope: write_orders).
if (!service) {
  const createRes = await fetch(`${BASE}/api/v1/fulfillment_services.json`, {
    method: 'POST',
    headers: json,
    body: JSON.stringify({
      name: 'Acme Shipping',
      callbackUrl: `${APP_URL}/api/tracking`,
      tracking_support: true,
    }),
  });
  service = (await createRes.json()).data?.fulfillment_service;
}
const serviceId = service.id;

// 3. Cache the serviceId on a shop metafield so subsequent fulfillment
//    writes can include it without a round-trip (scope: write_metafields).
await fetch(`${BASE}/api/v1/metafields.json`, {
  method: 'POST',
  headers: json,
  body: JSON.stringify({
    namespace: 'acme_shipping',
    key: 'fulfillment_service_id',
    value: String(serviceId),
    type: 'single_line_text_field',
    ownerType: 'shop',
    ownerId: storeId,
  }),
});

POST /api/v1/fulfillment_services.json requires the write_orders scope; reading the list requires read_orders. Writing the metafield requires write_metafields. See Fulfillment Services.

3. Push tracking after AWB assignment

When the merchant clicks Push to <Your App> in the admin order page (or your webhook auto-pushes), your app:

Calls your courier’s external API to create the shipment + assign a tracking number (AWB).
POSTs the resulting tracking number + courier name back to the platform via POST /api/v1/orders/:orderId/fulfillments.json.

// After your courier API returned { awb, courier_name, label_url }.
// POST /api/v1/orders/:orderId/fulfillments.json  (scope: write_orders)
const res = await fetch(
  `${BASE}/api/v1/orders/${orderId}/fulfillments.json`,
  {
    method: 'POST',
    headers: json,
    body: JSON.stringify({
      tracking_number: awb,
      tracking_company: courier_name,
      tracking_url: `https://your-tracking-domain.com/track/${awb}`,
      status: 'success',         // ← triggers the status flip
      service_id: serviceId,     // from step 2
      notify_customer: true,     // optional — send the shipment email
    }),
  },
);
const fulfillment = (await res.json()).data;

That single call:

Appends a new entry to the order’s fulfillments array.
Recomputes coverage and updates order.status:
- 100% covered → shipped (or delivered if status was set to delivered).
- Partially covered → partial.
Fires the fulfillments/create webhook to every subscriber.

4. Multi-package orders

For orders that ship in multiple packages, POST to the same orders/:orderId/fulfillments.json route once per package and pass the line_items subset that went in that package. The platform sums quantities per line_item.id across all success-state fulfillments to compute coverage.

const postFulfillment = (orderId, body) =>
  fetch(`${BASE}/api/v1/orders/${orderId}/fulfillments.json`, {
    method: 'POST',
    headers: json,
    body: JSON.stringify(body),
  });

// Package 1 — 2 of 5 items
await postFulfillment(orderId, {
  tracking_number: 'AWB-PKG-A',
  tracking_company: 'DHL Express',
  tracking_url: 'https://dhl.com/track/AWB-PKG-A',
  status: 'success',
  line_items: [
    { id: 'li_001', quantity: 1 },
    { id: 'li_002', quantity: 1 },
  ],
});
// → order.status flips paid → partial

// Package 2 — remaining 3 items
await postFulfillment(orderId, {
  tracking_number: 'AWB-PKG-B',
  tracking_company: 'FedEx Priority',
  tracking_url: 'https://fedex.com/track/AWB-PKG-B',
  status: 'success',
  line_items: [
    { id: 'li_003', quantity: 1 },
    { id: 'li_004', quantity: 1 },
    { id: 'li_005', quantity: 1 },
  ],
});
// → order.status flips partial → shipped

Omitting line_items is the back-compat shortcut for single-shipment orders: the fulfillment is treated as covering everything, so a single POST flips order.status straight to shipped.

5. Order lifecycle

pending → confirmed → paid → partial → shipped → delivered
                                    (canceled / abandoned as terminal off-ramps)

The auto-bump rule:

State of order	First success fulfillment (full coverage)	First success fulfillment (partial)
`pending`	→ `shipped`	→ `partial`
`confirmed`	→ `shipped`	→ `partial`
`paid`	→ `shipped`	→ `partial`
`partial`	→ `shipped` (once final package covers all)	(stays `partial`)
`shipped`	(unchanged — manual override respected)	(unchanged)
`delivered`	(unchanged — terminal)	(unchanged)
`canceled`	(unchanged — terminal)	(unchanged)

Pending / open / error / failure / cancelled fulfillment statuses never mutate order.status — only success (or shipped / delivered) do.

6. Admin UI

The merchant’s order detail page in the platform admin renders one package card per fulfillment, showing the courier name, tracking number (with copy button), tracking link, and the items in that package. The order status badge reflects the lifecycle above:

Paid (blue) — no shipments yet.
Partial (purple) — some packages out.
Shipped (green) — every item covered.

You don’t need to render this UI in your app — the platform handles it automatically once you’ve posted the fulfillment.

7. Optional: track status updates

Carriers expose tracking webhooks (or you can poll). When your app receives a status update from the carrier, mirror it to the platform via PUT /api/v1/fulfillments/:id.json so the order page reflects the latest status:

await fetch(
  `${PLATFORM_BASE}/api/v1/fulfillments/${fulfillmentId}.json`,
  {
    method: 'PUT',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${accessToken}`,
    },
    body: JSON.stringify({
      status: 'delivered',
    }),
  },
);

Setting status: 'delivered' will bump order.status to delivered provided no manual override has been applied.

Get Started

Guides

Extensions

Functions

App Bridge

Billing

AI & MCP

The full chain

Architecture at a glance

1. OAuth install handoff

2. Register as a fulfillment service

3. Push tracking after AWB assignment

4. Multi-package orders

5. Order lifecycle

6. Admin UI

7. Optional: track status updates

Full reference

​The full chain

​Architecture at a glance

​1. OAuth install handoff

​2. Register as a fulfillment service

​3. Push tracking after AWB assignment

​4. Multi-package orders

​5. Order lifecycle

​6. Admin UI

​7. Optional: track status updates

​Full reference

The full chain

Architecture at a glance

1. OAuth install handoff

2. Register as a fulfillment service

3. Push tracking after AWB assignment

4. Multi-package orders

5. Order lifecycle

6. Admin UI

7. Optional: track status updates

Full reference