Fulfilment

/api/integration/fulfilment — domain: Fulfilment

Three endpoints that together decide how an order ships and what the freight costs. All three are scoped by countryRegionCode, because the answer differs per country.

Domain. Fulfilment, which owns shipping options, postcode routing and freight charging.

PUT /postcode-routing

Purpose. Which carrier and service serve a postcode, and whether it defaults to road or air.

{
  "source": "BC",
  "timestamp": "2026-08-19T04:00:00Z",
  "data": [
    {
      "id": "AU-3000",
      "countryRegionCode": "AU",
      "postcode": "3000",
      "defaultRoadAgentCode": "TNT",
      "defaultRoadServiceCode": "ROAD",
      "defaultAirAgentCode": "TNT",
      "defaultAirServiceCode": "AIR",
      "defaultMethod": "Road"
    }
  ]
}

Field	Type	Required	Description
id	string	Yes	The natural key for this routing row
countryRegionCode	string	Yes	Which country's rules this row belongs to
postcode	string	Yes	Matched against the ship-to address to find this row
defaultRoadAgentCode	string		Carrier used for road delivery to this postcode
defaultRoadServiceCode	string		Carrier's service level for road
defaultAirAgentCode	string		Carrier used for air delivery to this postcode
defaultAirServiceCode	string		Carrier's service level for air
defaultMethod	string	Yes	Which method is offered by default. One of Road or Air

A destination with no matching postcode row cannot be quoted. That is not an error — the basket comes back priceable-except-shipping, with the reason attached.

PUT /freight-rates

Purpose. What freight costs, banded by weight and by order value.

{
  "source": "BC",
  "timestamp": "2026-08-19T04:00:00Z",
  "data": [
    {
      "id": "AU-TNT-ROAD-0-5",
      "countryRegionCode": "AU",
      "shippingAgentCode": "TNT",
      "shippingAgentServiceCode": "ROAD",
      "minWeight": 0,
      "maxWeight": 5,
      "minInvoiceValue": 0,
      "maxInvoiceValue": 250,
      "price": 12.50,
      "startDate": "2026-07-01T00:00:00+10:00",
      "endDate": null
    }
  ]
}

Field	Type	Required	Description
id	string	Yes	The natural key for this rate row
countryRegionCode	string	Yes	Which country's rules this row belongs to
shippingAgentCode	string	Yes	Carrier. Must match a code used in postcode routing
shippingAgentServiceCode	string	Yes	Service level. Must match a code used in postcode routing
minWeight	decimal		Lower bound of the weight band this rate covers
maxWeight	decimal		Upper bound of the weight band
minInvoiceValue	decimal		Lower bound of the order-value band
maxInvoiceValue	decimal		Upper bound of the order-value band. Free freight over a threshold is expressed here
price	decimal		The freight charge applied when the consignment falls in both bands
startDate	date-time		When the rate becomes valid. Null means no lower bound
endDate	date-time		When the rate stops being valid. Null means no upper bound

Bands must cover the range you expect to quote. A weight or value falling in a gap produces no rate, which surfaces to the customer as an unshippable basket.

PUT /airbags

Purpose. Named carton and satchel sizes with their dimensions, weight limit and freight cost, used when a consignment is charged by package rather than by weight band.

{
  "source": "BC",
  "timestamp": "2026-08-19T04:00:00Z",
  "data": [
    {
      "id": "AU-SATCHEL-3KG",
      "countryRegionCode": "AU",
      "description": "3kg satchel",
      "length": 40,
      "width": 30,
      "height": 10,
      "weight": 3,
      "freightCost": 9.95
    }
  ]
}

Field	Type	Required	Description
id	string	Yes	The natural key for this package type
countryRegionCode	string	Yes	Which country's rules this row belongs to
description	string		Human-readable name, for example "3kg satchel"
length	decimal		Internal length the package can accommodate
width	decimal		Internal width the package can accommodate
height	decimal		Internal height the package can accommodate
weight	decimal		Maximum weight the package can carry
freightCost	decimal		The charge for sending one of these

Response

All three answer with one entry per item, keyed by id.

{
  "data": [
    { "key": "AU-3000", "outcome": "Upserted" }
  ]
}