Shipping & Logistics

The ShippingService class (accessed via client.shipping) prices delivery for an address, lists a store’s delivery rates and pickup locations, returns live carrier options, and tracks parcels.

How an address is priced

A store’s delivery rates are its delivery zones, its distance rates and its “everywhere else” rate. An address is priced by:

The first zone that contains it — lowest priority first, then the zone created first. A zone is either an area drawn on a map (match_kind: area) or a set of countries, optionally narrowed to postcode prefixes (match_kind: region).
Otherwise, the distance rate whose range contains its distance from the store. A range includes its min_distance_meters and stops just before its max_distance_meters, so 0–10 km and 10–50 km share the 10 km point without overlapping.
Otherwise, the “everywhere else” rate. When the store has zones or distance rates but no “everywhere else” rate, or has chosen not to deliver outside them (everywhere_else.refuse), an address outside them is not delivered to. calculateShipping then returns only the store’s pickup options, or answers 400 shipping_not_deliverable when the store offers no pickup.

A matched rate is free when the order reaches its free-delivery threshold. A store with no delivery rates at all charges nothing through them (applied_rule: none, configured: false). Every amount is in the store’s own currency, returned as currency.

Delivery options and pickup

A matched rate is the order’s standard delivery option. The store can add named options to the same rate — Express, Next day — each with its own fee, estimate and conditions such as an order-total range or a parcel weight range. A store can also offer pickup at any of its locations, each with its own pickup fee, an optional minimum order, and a note on when orders are ready. The store can set rules for product categories: a surcharge per order or per item, delivery only to nearby addresses (the store’s map zones and distance rates, not its country-wide zones or “everywhere else” rate), or collection only. These rules, and options that depend on parcel weight, apply when the basket’s lines are sent to calculateShipping as items.

Methods

`getShippingZones`

Retrieve the store’s delivery rates and pickup locations: active distance rates, active delivery zones, the “everywhere else” rate, and the locations where shoppers can collect an order. Useful for showing delivery coverage, likely costs, or a “collect in store” option early in the shopping journey.

const { currency, pricing_tiers, delivery_zones, everywhere_else, pickup_locations } = await client.shipping.getShippingZones();

Response

{
  "currency": "USD",
  "pricing_tiers": [
    { "tier_name": "Local (within 10 km)", "min_distance_meters": 0, "max_distance_meters": 10000, "delivery_fee": 5.99, "free_delivery_threshold": 75, "is_active": true, "priority": 1 },
    { "tier_name": "Metro (10–50 km)", "min_distance_meters": 10000, "max_distance_meters": 50000, "delivery_fee": 9.99, "free_delivery_threshold": 150, "is_active": true, "priority": 2 }
  ],
  "delivery_zones": [
    { "zone_name": "Lower 48 states", "delivery_fee": 12.99, "free_delivery_threshold": 200, "is_active": true, "priority": 1, "color": "#3B82F6", "match_kind": "region", "countries": ["US"], "postcodes": [] }
  ],
  "everywhere_else": { "refuse": false, "delivery_fee": 29.99, "free_delivery_threshold": null },
  "pickup_locations": [
    {
      "id": "3d5c7a10-8b2e-4f61-9c4d-1a2b3c4d5e6f",
      "name": "Brooklyn store",
      "address": { "line1": "145 Atlantic Avenue", "city": "Brooklyn", "state": "NY", "postal_code": "11201", "country": "US" },
      "latitude": 40.6907,
      "longitude": -73.9956,
      "hours": "Mon–Sat 10:00–19:00",
      "pickup_fee": 0,
      "minimum_order": null,
      "ready_text": "Ready in 2 hours",
      "instructions": "Collect from the counter at the back of the store."
    }
  ]
}

everywhere_else is null when the store has none. When refuse is true, the store does not deliver outside its zones and distance rates, and both amounts are null. A region zone covers the addresses in its countries; when postcodes is not empty, only postcodes beginning with one of those prefixes. pickup_locations lists the primary location first and is empty when the store does not offer pickup. The response is cached for up to 60 seconds and carries an ETag; calculateShipping and order creation always read the current rates.

`calculateShipping`

Calculate the ways a shopper can receive an order — the store’s delivery options and pickup locations — priced for their address and basket.

// Exact coordinates give the most precise match (recommended).
const shipping = await client.shipping.calculateShipping({
  requestBody: {
    latitude: 40.6782,
    longitude: -73.9442,
    order_total: 50
  }
});

// A human-readable address or landmark; Galactic Core resolves it to coordinates.
const shipping = await client.shipping.calculateShipping({
  requestBody: {
    place_name: "Brooklyn, New York",
    order_total: 50
  }
});

// Country, postcode and the basket's lines let country-wide zones, weight-based
// options and the store's category rules apply.
const shipping = await client.shipping.calculateShipping({
  requestBody: {
    latitude: 40.6782,
    longitude: -73.9442,
    country_code: "US",
    postal_code: "11225",
    order_total: 50,
    items: [{ variant_id: "15ca5a86-4b1b-47c3-8762-a1aa43941565", quantity: 2 }]
  }
});

Response

{
  "fee": 9.99,
  "currency": "USD",
  "zone_name": null,
  "tier_name": "Metro (10–50 km)",
  "distance_meters": 18432,
  "is_free": false,
  "free_threshold": 150,
  "configured": true,
  "reason": "Metro (10–50 km)",
  "applied_rule": "distance",
  "rate_source": "tier",
  "coordinates": { "latitude": 40.6782, "longitude": -73.9442, "country_code": "US", "postal_code": "11225" },
  "deliverable": true,
  "restriction": "none",
  "options": [
    { "id": "place", "method": "delivery", "name": "Standard delivery", "fee": 9.99, "currency": "USD", "is_free": false, "estimate": null, "available": true, "free_threshold": 150 },
    { "id": "opt:9a1f3c2e-5b7d-4e8a-a2c4-6d8e0f1a3b5c", "method": "delivery", "name": "Express", "fee": 19.99, "currency": "USD", "is_free": false, "estimate": "Next business day", "available": true },
    {
      "id": "pickup:3d5c7a10-8b2e-4f61-9c4d-1a2b3c4d5e6f",
      "method": "pickup",
      "name": "Pickup at Brooklyn store",
      "fee": 0,
      "currency": "USD",
      "is_free": true,
      "estimate": "Ready in 2 hours",
      "available": true,
      "location": {
        "id": "3d5c7a10-8b2e-4f61-9c4d-1a2b3c4d5e6f",
        "name": "Brooklyn store",
        "address": { "line1": "145 Atlantic Avenue", "city": "Brooklyn", "state": "NY", "postal_code": "11201", "country": "US" },
        "latitude": 40.6907,
        "longitude": -73.9956,
        "hours": "Mon–Sat 10:00–19:00",
        "instructions": "Collect from the counter at the back of the store.",
        "distance_meters": 3412.57
      }
    }
  ],
  "fulfilled_from": null
}

order_total is the order’s merchandise total in the store’s currency (e.g. 50 = $50.00), not a minor-unit (cents) value — the line totals after any discount. It decides whether the order reaches the matched rate’s free-delivery threshold.

Request Fields:

Field	Description
`latitude` / `longitude`	The shopper’s location. Send these, or `place_name`.
`place_name`	An address or place, resolved to a location.
`country_code`	Optional ISO 3166-1 alpha-2 country code. Matches country-wide zones; takes precedence over the country found from the location.
`postal_code`	Optional postcode, at most 16 characters. Matches zones narrowed to postcode prefixes; takes precedence over the postcode found from the location.
`order_total`	The merchandise after discounts, before tax and shipping. Defaults to `0`.
`items`	Optional basket lines, `{ variant_id, quantity }`, at most 500. With them, weight-based options and the store’s category rules apply.
`address_to` / `address_from` / `parcel`	For live carrier options (below).

Response Fields:

Field	Description
`fee`	The standard delivery charge (the `place` option’s fee), in `currency`. `null` on a carrier-options-only request, and when the store does not deliver to the address but offers pickup.
`currency`	The currency of `fee` and `free_threshold` — the store’s own.
`applied_rule`	Which rate priced the address: `zone`, `distance`, `fallback` (the “everywhere else” rate) or `none` (no delivery rates, or a carrier-options-only request).
`rate_source`	Which source produced the result: `zone`, `tier`, `fallback`, `shippo`, `custom` or `none`.
`is_free`	`true` when no delivery charge applies to this order.
`free_threshold`	The order total from which the matched rate delivers free, or `null`.
`configured`	Whether the store has any delivery rates.
`zone_name` / `tier_name`	The zone or distance rate that priced the address, when one did.
`distance_meters`	Distance from the store to the address, when it was measured.
`coordinates`	The resolved location, including when you sent a `place_name`, with the country and postcode used to match zones when known.
`deliverable`	`false` when the store does not deliver to the address — because it is outside the delivery area, or an item in the basket can only be collected — and only pickup options are returned.
`restriction`	A limit from the store’s category rules: `none`, `local_only` (map zones and distance rates only) or `pickup_only` (collection only).
`options`	Every way the shopper can receive the order: the delivery options first, then the pickup locations, nearest first. Each carries `id`, `method` (`delivery` or `pickup`), `name`, `fee`, `currency`, `is_free`, `estimate`, `available`, and where they apply `free_threshold`, `minimum_order` and, for pickup, `location`.
`fulfilled_from`	When the store delivers from whichever of its locations is nearest the shopper, that location (`id`, `name`, `distance_meters`); distance rates are measured from it. Otherwise `null`.

Option ids take three forms: place is the standard delivery option, opt:<id> is a named option the store added to the same rate, and pickup:<location id> is collection at that location. An option with available: false does not apply to this basket — usually a pickup location whose minimum_order the order has not reached — and cannot be ordered with. To order with an option, pass its id as shipping_option_id on createOrder, with shipping_amount equal to its fee. For a pickup option, also send fulfillment_method: 'pickup' and the location’s id as pickup_location_id; the order then needs no shipping address. When the store does not deliver to the address but offers pickup, the response is 200 with deliverable: false, fee: null, applied_rule: none and only the pickup options:

Response

{
  "fee": null,
  "currency": "USD",
  "zone_name": null,
  "tier_name": null,
  "distance_meters": null,
  "is_free": false,
  "free_threshold": null,
  "configured": true,
  "reason": "This address is outside the delivery area",
  "applied_rule": "none",
  "coordinates": { "latitude": 41.8781, "longitude": -87.6298 },
  "rate_source": "none",
  "deliverable": false,
  "restriction": "none",
  "options": [
    {
      "id": "pickup:3d5c7a10-8b2e-4f61-9c4d-1a2b3c4d5e6f",
      "method": "pickup",
      "name": "Pickup at Brooklyn store",
      "fee": 0,
      "currency": "USD",
      "is_free": true,
      "estimate": "Ready in 2 hours",
      "available": true,
      "location": {
        "id": "3d5c7a10-8b2e-4f61-9c4d-1a2b3c4d5e6f",
        "name": "Brooklyn store",
        "address": { "line1": "145 Atlantic Avenue", "city": "Brooklyn", "state": "NY", "postal_code": "11201", "country": "US" },
        "latitude": 40.6907,
        "longitude": -73.9956,
        "hours": "Mon–Sat 10:00–19:00",
        "instructions": "Collect from the counter at the back of the store.",
        "distance_meters": 1146320.4
      }
    }
  ],
  "fulfilled_from": null
}

Live carrier rates (multi-carrier)

When the store has a carrier account connected, or its own custom shipping extension, send a destination address_to and a parcel to also receive live carrier options in rates[]. Each option carries its source — the store’s carrier account (shippo) or its custom shipping extension (custom).

const quote = await client.shipping.calculateShipping({
  requestBody: {
    latitude: 40.748, longitude: -73.985, order_total: 120,
    address_to: { street1: '350 5th Ave', city: 'New York', state: 'NY', zip: '10118', country: 'US' },
    parcel: { length: '10', width: '8', height: '4', distance_unit: 'in', weight: '2', mass_unit: 'lb' },
  },
});

To request carrier options only, send address_to and parcel with no coordinates or place name. The store’s own rate is then not priced (there is no location to price it from), so fee is null and applied_rule is none. A store with no carrier connected answers that request with 400 provider_not_configured. To order with a carrier option, pass its rate_id as shipping_rate_id and its source as shipping_rate_source on createOrder (with shipping_parcel for a custom-extension option). The option is fetched again from its source and checked before it is charged.

Buying a shipping label is done by the merchant from their admin — it charges the merchant’s carrier account, marks the order shipped, and emits order.shipped — so there is no SDK method for it. From a storefront you quote rates (calculateShipping) and track parcels (trackShipment).

`trackShipment`

Returns live tracking status for a parcel by carrier and tracking number, for rendering the status timeline inside your own UI. A secret key tracks any parcel on the store’s carrier account; a publishable key tracks only a tracking number that is on one of the store’s own orders, so a storefront can show a shopper their own parcel.

const status = await client.shipping.trackShipment({ carrier: 'usps', number: order.tracking_number });

Response

{
  "carrier": "usps",
  "tracking_number": "9400111899223197428490",
  "status": "TRANSIT",
  "status_details": "Arrived at USPS Regional Facility",
  "eta": "2026-08-07T17:00:00Z",
  "history": [
    {
      "status": "TRANSIT",
      "status_details": "Arrived at USPS Regional Facility",
      "status_date": "2026-08-04T09:12:00Z",
      "location": { "city": "Springfield", "state": "VA", "country": "US" }
    },
    {
      "status": "TRANSIT",
      "status_details": "Accepted at USPS Origin Facility",
      "status_date": "2026-08-03T18:40:00Z",
      "location": { "city": "Richmond", "state": "VA", "country": "US" }
    }
  ]
}

The lightest way to let a shopper track is to link to the carrier’s own tracking page — no API call. When the label is bought, the carrier tracking URL is saved on the order at shipping_metadata.shippo.tracking_url; render it as a “Track your package” link. Use trackShipment only when you want the status shown natively in your storefront.

Response Codes

All three methods accept publishable and secret keys. calculateShipping uses POST purely to carry a structured request body — it is read-only.

`getShippingZones` (`GET /v1/shipping/zones`)

Code	Meaning
`200`	Delivery rates returned.
`304`	Not modified (you sent a matching `If-None-Match`).
`401`	Invalid or missing API key.
`403`	Forbidden (e.g., key disabled or store suspended).
`429`	Rate limit exceeded.
`500`	Internal server error.

`calculateShipping` (`POST /v1/shipping/calculate`)

Code	Meaning
`200`	Charge calculated and returned.
`400`	`invalid_request` (a location outside -90..90 / -180..180, an `order_total` that is not a number of zero or more, a `country_code` that is not two letters, a `postal_code` longer than 16 characters, malformed `items`, or no location at all), `geocoding_failed` (a `place_name` could not be found), `shipping_not_deliverable` (the store neither delivers to the location nor offers pickup), or `provider_not_configured` (a carrier-options-only request to a store with no carrier connected).
`401`	Invalid or missing API key.
`403`	Forbidden (e.g., key disabled or store suspended).
`429`	Rate limit exceeded.
`500`	Internal server error.

`trackShipment` (`GET /v1/shipping/tracking/{carrier}/{number}`)

Code	Meaning
`200`	Tracking status returned.
`400`	Invalid carrier or tracking number.
`401`	Invalid or missing API key.
`404`	With a publishable key, the tracking number is not on any of the store’s orders.
`429`	Rate limit exceeded.
`502`	The carrier’s tracking service could not be reached (`tracking_unavailable`).

Get Started

Core Commerce

Discovery

Checkout & Logistics

Agents

Marketplace

B2B (Wholesale)

Account & Support

System & Store

Integrations

How an address is priced

Delivery options and pickup

Methods

`getShippingZones`

`calculateShipping`

Live carrier rates (multi-carrier)

`trackShipment`

Response Codes

`getShippingZones` (`GET /v1/shipping/zones`)

`calculateShipping` (`POST /v1/shipping/calculate`)

`trackShipment` (`GET /v1/shipping/tracking/{carrier}/{number}`)

​How an address is priced

​Delivery options and pickup

​Methods

​getShippingZones

​calculateShipping

​Live carrier rates (multi-carrier)

​trackShipment

​Response Codes

​getShippingZones (GET /v1/shipping/zones)

​calculateShipping (POST /v1/shipping/calculate)

​trackShipment (GET /v1/shipping/tracking/{carrier}/{number})

How an address is priced

Delivery options and pickup

Methods

`getShippingZones`

`calculateShipping`

Live carrier rates (multi-carrier)

`trackShipment`

Response Codes

`getShippingZones` (`GET /v1/shipping/zones`)

`calculateShipping` (`POST /v1/shipping/calculate`)

`trackShipment` (`GET /v1/shipping/tracking/{carrier}/{number}`)