Shipping

Get shipping rates and create shipments

The Shipping module integrates with shipping providers (e.g. Shippo) to get live rates and purchase shipping labels for orders.

Get Shipping Rates

POST /v1/stores/{storeId}/orders/{orderId}/shipping/rates

SDK: sdk.shipping.getRates()

Get available shipping rates for an order’s package.

const { rates } = await sdk.shipping.getRates({
  order_id: 'ord_abc123',
  shipping_provider_id: 'integration_shippo_123',
  from_address: {
    name: 'Warehouse',
    street1: '123 Sender St',
    city: 'San Francisco',
    state: 'CA',
    postal_code: '94102',
    country: 'US',
  },
  to_address: {
    name: 'Jane Doe',
    street1: '456 Profile Ave',
    city: 'New York',
    state: 'NY',
    postal_code: '10001',
    country: 'US',
  },
  parcel: {
    length: 10,
    width: 8,
    height: 4,
    weight: 2,
    distance_unit: 'in',
    mass_unit: 'lb',
  },
});

rates.forEach(rate => {
  console.log(`${rate.carrier} ${rate.service}: $${rate.amount / 100} (${rate.estimated_days} days)`);
});

Parameters

Name	Type	Description
`order_id` required	`string`	Order ID to get rates for
`shipping_provider_id` required	`string`	Shipping integration ID
`from_address` required	`Address`	Origin address
`to_address` required	`Address`	Destination address
`parcel` required	`Parcel`	Package dimensions and weight
`customs_declaration` optional	`CustomsDeclaration`	Customs info for international shipments

Parcel Object

Parameters

Name	Type	Description
`length` required	`number`	Package length
`width` required	`number`	Package width
`height` required	`number`	Package height
`weight` required	`number`	Package weight
`distance_unit` required	`string`	Distance unit (in, cm)
`mass_unit` required	`string`	Weight unit (oz, lb, g, kg)

Rate Response

{
  "rates": [
    {
      "id": "rate_abc",
      "provider": "shippo",
      "carrier": "usps",
      "service": "priority",
      "display_name": "USPS Priority Mail",
      "amount": 895,
      "currency": "USD",
      "estimated_days": 3
    }
  ]
}

Create Shipment

POST /v1/stores/{storeId}/orders/{orderId}/ship

SDK: sdk.shipping.ship()

Purchase a shipping label and create a shipment for an order. Returns a shipmentId, trackingNumber, optional trackingUrl, and labelUrl.

const result = await sdk.shipping.ship({
  order_id: 'ord_abc123',
  rate_id: 'rate_abc',
  carrier: 'usps',
  service: 'priority',
  location_id: 'loc_warehouse',
  lines: [
    { order_item_id: 'item_1', quantity: 2 },
    { order_item_id: 'item_2', quantity: 1 },
  ],
});

console.log(result.tracking_number, result.label_url);

Parameters

Name	Type	Description
`order_id` required	`string`	Order ID
`rate_id` required	`string`	Rate ID from getRates response
`carrier` required	`string`	Carrier code (usps, fedex, ups, etc.)
`service` required	`string`	Service level (priority, express, etc.)
`location_id` required	`string`	Fulfillment location ID
`lines` required	`ShipmentLine[]`	Items being shipped

ShipmentLine Object

Parameters

Name	Type	Description
`order_item_id` required	`string`	Order item ID
`quantity` required	`number`	Quantity being shipped

Customs Declaration (International)

For international shipments, include a customs declaration when fetching rates:

const { rates } = await sdk.shipping.getRates({
  // ... other params
  customs_declaration: {
    contents_type: 'MERCHANDISE',
    contents_explanation: 'Clothing items',
    non_delivery_option: 'RETURN',
    certify: true,
    certify_signer: 'John Doe',
    items: [
      {
        description: 'T-Shirt',
        quantity: 2,
        net_weight: '0.5',
        mass_unit: 'lb',
        value_amount: '25.00',
        value_currency: 'USD',
        origin_country: 'US',
      },
    ],
  },
});

Note

Addresses use the standard arky Address shape: name, street1, optional street2, city, state, postalCode, country, and optional company, phone, email.