API key configuration

Every API key belongs to a module: the row you created under Settings > Integrations in the members area. The module holds settings that shape the quotes made with that key, such as default parcel size, quote display, surcharges, rules, order boxing and pickup warehouse. These endpoints read and change those settings, and check a key.

They exist mainly for store plugins, which read their settings this way. If you are building your own integration, you usually only need api_details/full to see how your key is set up, and you can change the settings on the key’s page in the members area instead.

Purpose	Request
Settings summary	GET /api/v5/bookings/v4/api_details
Full configuration	GET /api/v5/bookings/v4/api_details/full
Save settings	POST /api/v5/bookings/v4/set_api_settings
Check a key	POST /api/v5/bookings/v4/test_api_key_settings
Order sync settings	GET /api/v5/bookings/sync

The /v4 in these paths is part of the name: these are the current and only paths for key configuration on the v5 API.

All five use your API key in the api-key header. See Authentication. Each one acts on the module of the key you send.

Get the full configuration

GET /api/v5/bookings/v4/api_details/full

Returns the key’s identity, its complete stored settings, pickup warehouses, pricing rules and package-type rules. Use it to find out why a quote looks the way it does.

curl "https://api.transdirect.com.au/api/v5/bookings/v4/api_details/full" \
  -H "api-key: $TD_API_KEY"

import { client, getApiV5BookingsV4ApiDetailsFull } from '@transdirect/api-sdk';

client.setConfig({ headers: { 'api-key': process.env.TD_API_KEY! } });

const { data, error } = await getApiV5BookingsV4ApiDetailsFull();
console.log(data?.api_key.demo_mode, data?.warehouses);

Response

200 OK:

{
  "api_key": {
    "id": 4567,
    "member_id": 12345,
    "status": true,
    "demo_mode": false,
    "module_type_id": 4,
    "site_domain": "https://shop.example.com.au",
    "created": "2026-10-01 09:15:00"
  },
  "module_setting": {
    "default_height": "10",
    "default_width": "10",
    "default_lenght": "10",
    "default_weight": "5",
    "module_dispay_mode": "full_mode",
    "enabled_courier": []
  },
  "warehouses": [
    {
      "id": 901,
      "suburb": "SYDNEY",
      "postcode": "2000",
      "state": "NSW",
      "type": "business",
      "created": "2026-10-01 09:15:00"
    }
  ],
  "rules": [],
  "package_type_rules": []
}

Field	Type	Description
api_key	object	id (the module id), member_id, status (true when active), demo_mode (true when the Demo courier is on, see Testing with demo mode), module_type_id, site_domain (the Store URL you entered) and created.
module_setting	object	Every stored setting for the module, as saved. Which keys appear depends on what has been set. Some key names are misspelt and are used as is, for example default_lenght, quote_diplay and module_dispay_mode.
warehouses	array	Pickup addresses for the module: id, suburb, postcode, state, type (business or residential), created.
rules	array	Shipping rules that change quote prices, in the order they are applied. Each has type, trigger_comparison, trigger_value, action_operator, action_value, readable trigger_description and action_description, priority, and couriers (empty means every courier).
package_type_rules	array	Rules that pick a package type by range: package_type, base_on, range_from, range_to.

module_type_id is 4 for a Custom API key, 1 for the WooCommerce plugin, 2 for Shopify, 3 for Magento and 5 for a WooCommerce store connected without the plugin. On a Custom API key the module’s courier selection (enabled_courier) does not restrict which couriers you are quoted.

Order boxing settings, when set, are in module_setting: group_box (on when enabled), minimum_fill, minimum_fill_percent, and the box sizes as parallel lists box_length, box_width, box_height and box_weight. See Order boxing.

Get the settings summary

GET /api/v5/bookings/v4/api_details

Returns a fixed set of the module’s settings, each as stored (an empty string when not set). This is the shape store plugins read.

curl "https://api.transdirect.com.au/api/v5/bookings/v4/api_details" \
  -H "api-key: $TD_API_KEY"

import { getApiV5BookingsV4ApiDetails } from '@transdirect/api-sdk';

// client configured with your api-key header, as above
const { data, error } = await getApiV5BookingsV4ApiDetails();

200 OK:

{
  "module_id": 4567,
  "module_title": "",
  "shipping_title": "Transdirect Shipping",
  "street_type": "business",
  "default_height": "10",
  "default_width": "10",
  "default_lenght": "10",
  "default_weight": "5",
  "enable_sync": "on",
  "sync_from_date": "2026-10-01",
  "quote_diplay": "display_all",
  "surcharge_amount": "",
  "enabled_courier": [],
  "mode": "full_mode",
  "sync_all_order": ""
}

Field	Description
module_id	The module (key) id.
module_title	The module’s name.
shipping_title	Name of the shipping method shown to buyers at checkout.
street_type	Default delivery address type: business or residential.
default_lenght, default_width, default_height	Default parcel size in cm, used when an item has no dimensions.
default_weight	Default parcel weight in kg.
enable_sync, sync_all_order	Order sync switches: on when enabled.
sync_from_date	Earliest order date to sync.
quote_diplay	Which quotes are returned: display_all, display_cheapest or display_cheapest_fastest. This also applies to quotes you request through the API with this key, so display_cheapest gives you a single quote.
surcharge_amount	General surcharge amount. It is only added to quotes while Apply general surcharge is ticked on the key’s page in the members area.
enabled_courier	Courier keys the store shows. Empty means no restriction.
mode	WooCommerce plugin display mode: full_mode, simplified_mode or no_display_mode.

Save settings

POST /api/v5/bookings/v4/set_api_settings

This changes live settings

Saving changes the settings for this key straight away, and every quote made with the key after that uses them. If the key runs a live store, its checkout rates change too. Read the current values with api_details/full first, and send only the fields you mean to change.

Send JSON. Fields you leave out keep their stored value. Unknown fields are ignored.

Field	Type	Saved as	Description
trans_title	string	shipping_title	Shipping method name shown to buyers.
address_type	string	street_type	business or residential. Commercial is saved as business.
length, width, height	string	default_lenght, default_width, default_height	Default parcel size in cm. Each side must be a positive number, and at least one side must be 5 cm or more. Leave all three empty to use the standard package size.
weight	string	default_weight	Default parcel weight in kg.
quotes	string	quote_diplay	display_all, display_cheapest or display_cheapest_fastest.
surcharge_price	string	surcharge_amount	General surcharge amount. It only takes effect while Apply general surcharge is ticked on the key’s page in the members area; this endpoint cannot tick it.
unit	string	surcharge_amount_currency	Surcharge type: cu for dollars, pr for percent.
enable_order	string	enable_sync	yes turns order sync on, any other value turns it off.
order_date	string	sync_from_date	Earliest order date to sync (YYYY-MM-DD).
order_status	string or array	sync_<status>	Store order statuses, for example ["Processing","Completed"]. Sending this replaces the previous list. The list is stored but does not currently filter anything: order sync settings report every status as on whenever sync is on.
enabled_group_box	string	group_box	yes turns order boxing on, any other value turns it off.
box_size	string	group_box_size	Stored only. Boxing uses the box sizes set in the members area (box_length, box_width, box_height, box_weight), not this value.
cor_<courier key>	string	enabled_courier	For example "cor_couriers_please": "yes". If you send any cor_ field, the courier list becomes exactly the couriers sent with yes. Has no effect on a Custom API key’s quotes.
postcode	array	warehouse	One pickup address as "<postcode>,<SUBURB>", for example ["2000,SYDNEY"]. The state is looked up from the pair. This updates the first existing warehouse for the key (lowest id), or creates one if none exists, and also changes the address on your Transdirect account. Other warehouses and omitted address fields are preserved; an unsuccessful suburb lookup preserves the stored state.
postcode_type	array	warehouse	Address type for that pickup address, for example [["business"]]. If omitted, the existing warehouse and account address types are preserved.

The legacy WooCommerce setup value authtype: "Email and Password" intentionally creates a new API key and returns {"API-Key":"..."} in place of true, matching PHP v4. The account-address update from postcode also matches PHP v4. Omit authtype when updating an existing key.

Saving here or changing module settings, pricing rules, courier assignments or package-type rules in the members area invalidates the member and module quote caches. Cache invalidation is best effort; already-running quotes may finish with earlier settings.

curl -X POST "https://api.transdirect.com.au/api/v5/bookings/v4/set_api_settings" \
  -H "api-key: $TD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "trans_title": "Transdirect Shipping",
    "length": "30",
    "width": "20",
    "height": "15",
    "weight": "2"
  }'

import { postApiV5BookingsV4SetApiSettings } from '@transdirect/api-sdk';

// client configured with your api-key header, as above
const { data, error } = await postApiV5BookingsV4SetApiSettings({
  body: { trans_title: 'Transdirect Shipping', length: '30', width: '20', height: '15', weight: '2' },
});

200 OK with the body true.

Check a key

POST /api/v5/bookings/v4/test_api_key_settings

Tells you which account and module a key belongs to and whether it is active. Unlike every other endpoint, it also answers for a deactivated key. Send the key in the api-key header and no body.

curl -X POST "https://api.transdirect.com.au/api/v5/bookings/v4/test_api_key_settings" \
  -H "api-key: $TD_API_KEY"

import { postApiV5BookingsV4TestApiKeySettings } from '@transdirect/api-sdk';

// client configured with your api-key header, as above
const { data, error } = await postApiV5BookingsV4TestApiKeySettings();

For a known key, 200 OK with JSON:

{
  "id": 4567,
  "member_id": 12345,
  "status": 1,
  "module_type_id": 4,
  "member_email": "accounts@example.com.au"
}

status is 1 for an active key and 0 for a deactivated one.

For a missing or unknown key the status is still 200, but the body is the plain text API is invalid (Content-Type: text/plain). Check the content type before parsing JSON.

Get order sync settings

GET /api/v5/bookings/sync

Tells a store plugin which of its orders to send to Transdirect.

curl "https://api.transdirect.com.au/api/v5/bookings/sync" \
  -H "api-key: $TD_API_KEY"

import { getApiV5BookingsSync } from '@transdirect/api-sdk';

// client configured with your api-key header, as above
const { data, error } = await getApiV5BookingsSync();

200 OK. When order sync is on (enable_sync or the import-every-order switch), every status is "on":

{
  "shipping_title": "Transdirect Shipping",
  "pending": "on",
  "processing": "on",
  "onhold": "on",
  "completed": "on",
  "cancelled": "on",
  "refunded": "on",
  "failed": "on",
  "multiwarehouse_enabled": "off"
}

When order sync is off, the statuses are replaced by "enable_sync": "disabled":

{
  "shipping_title": "Transdirect Shipping",
  "enable_sync": "disabled",
  "multiwarehouse_enabled": "off"
}

multiwarehouse_enabled is on when Enable multi warehouse is ticked on the module’s page. That setting appears only on WooCommerce plugin modules.

Errors

Status	Body	Cause
400	{"error":"Default package size must be a positive measurement in centimetres. Leave the boxes empty to use the standard package size."}	set_api_settings: a dimension is zero, negative or not a number.
400	{"error":"Default package size is too small to be a real parcel. Enter at least 5cm on a side, or leave the boxes empty to use the standard package size."}	set_api_settings: every side is under 5 cm.
400	{"success":false,"error":{"name":"ZodError","message":"..."}}	set_api_settings: a known field has the wrong type, for example postcode sent as a string instead of a list.
401	{"error":"missing_api_key"} or {"error":"invalid_api_key"}	No key, or the key is unknown or deactivated. Not returned by test_api_key_settings.
404	{"error":"api_key_not_found"} (plain text api_key_not_found from set_api_settings)	The key’s module could not be found.
429	{"error":"rate_limited"}	More than 600 requests in a minute on this key. Wait for the number of seconds in retry-after.

Try it

These operations are under api-settings in the API Explorer. Paste your API key into the authentication box and send a request. The two GET requests and test_api_key_settings are safe to try. set_api_settings changes your live settings.

Related

• Order boxing
• Authentication
• Plugins and integrations