Shipping

Get shipping rates and create shipments

The Shipping module quotes rates, purchases labels, and tracks order fulfillment. Arky selects the backend shipping route and returns carrier, service, rate, tracking, and label details.

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",
	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 Contact 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
`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",
			"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",
	fulfillment_order_id: "fo_abc123",
	lines: [
		{
			order_item_id: "item_1",
			fulfillment_order_line_id: "fol_1",
			quantity: 2,
		},
		{
			order_item_id: "item_2",
			fulfillment_order_line_id: "fol_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
`fulfillment_order_id` optional	`string`	Fulfillment order being shipped. Recommended for new orders.
`lines` required	`ShipmentLine[]`	Items being shipped

ShipmentLine Object

Parameters

Name	Type	Description
`order_item_id` required	`string`	Order item ID
`fulfillment_order_line_id` optional	`string`	Fulfillment order line being satisfied
`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.