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/businesses/{businessId}/orders/{orderId}/shipping/rates

SDK: sdk.shipping.getRates()

Get available shipping rates for an order’s package.

const { rates } = await sdk.shipping.getRates({
  orderId: 'ord_abc123',
  shippingProviderId: 'integration_shippo_123',
  fromAddress: {
    name: 'Warehouse',
    street1: '123 Sender St',
    city: 'San Francisco',
    state: 'CA',
    postalCode: '94102',
    country: 'US',
  },
  toAddress: {
    name: 'Jane Doe',
    street1: '456 Customer Ave',
    city: 'New York',
    state: 'NY',
    postalCode: '10001',
    country: 'US',
  },
  parcel: {
    length: 10,
    width: 8,
    height: 4,
    weight: 2,
    distanceUnit: 'in',
    massUnit: 'lb',
  },
});

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

Parameters

Name	Type	Description
`orderId` required	`string`	Order ID to get rates for
`shippingProviderId` required	`string`	Shipping integration ID
`fromAddress` required	`Address`	Origin address
`toAddress` required	`Address`	Destination address
`parcel` required	`Parcel`	Package dimensions and weight
`customsDeclaration` 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
`distanceUnit` required	`string`	Distance unit (in, cm)
`massUnit` required	`string`	Weight unit (oz, lb, g, kg)

Rate Response

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

Create Shipment

POST /v1/businesses/{businessId}/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({
  orderId: 'ord_abc123',
  rateId: 'rate_abc',
  carrier: 'usps',
  service: 'priority',
  locationId: 'loc_warehouse',
  lines: [
    { orderItemId: 'item_1', quantity: 2 },
    { orderItemId: 'item_2', quantity: 1 },
  ],
});

console.log(result.trackingNumber, result.labelUrl);

Parameters

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

ShipmentLine Object

Parameters

Name	Type	Description
`orderItemId` 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
  customsDeclaration: {
    contentsType: 'MERCHANDISE',
    contentsExplanation: 'Clothing items',
    nonDeliveryOption: 'RETURN',
    certify: true,
    certifySigner: 'John Doe',
    items: [
      {
        description: 'T-Shirt',
        quantity: 2,
        netWeight: '0.5',
        massUnit: 'lb',
        valueAmount: '25.00',
        valueCurrency: 'USD',
        originCountry: 'US',
      },
    ],
  },
});

Note

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