API

This page documents how shipment request identifier fields are normalized before validation and booking. The behavior here is based on the current pipeline in the api repository.

Resolution Order

Shipment requests are normalized in this order:

organizationId can switch the tenant context to a descendant organization.
senderId and receiverId try to fill sender and receiver.
organizationId can fill sender from the selected organization profile when sender and senderId are missing.
consignmentTemplateId or auto-apply templates are merged into the request.
a service-specific pickup address can fill pickupAddress.
senderAddressId and receiverAddressId can overwrite sender and receiver late in the pipeline.
freightPayerId or freightPayer.customerNumber can fill freightPayer and carrier-contract context.

Later resolvers win over earlier ones.

Field Summary

Field	Accepts	Resolves	Overwrite behavior
`organizationId`	descendant organization `ulid` or `quick_id`	tenant context, sometimes `sender`	does not fill `sender` if `senderId` or `sender` is already present
`senderId`	in practice a sender address `quick_id`	`sender`	if found, it replaces the inline `sender` payload
`receiverId`	in practice a receiver address `quick_id`	`receiver`	if found, it replaces the inline `receiver` payload
`consignmentTemplateId`	template `id` or `quick_id`	template payload	request wins in normal mode, template wins in override mode
`senderAddressId`	address-book `id` or `quick_id`	`sender`	runs late, so it also overrides `senderId` and organization sender fill
`receiverAddressId`	address-book `id` or `quick_id`	`receiver`	runs late, so it also overrides `receiverId`
`freightPayerId`	address-book `id` or `quick_id`	`freightPayer` and contract context	only works when the address has a contract for the given `serviceId`
`organizationMemberId`	existing `organization_members.id`	nothing	currently validation only

organizationId

organizationId does not fetch a sender address from the address book. It first tries to switch tenant context.

Behavior:

descendant organization ulid or quick_id can switch tenant context
numeric database id does not switch tenant context
personal user tokens without organization context do not switch tenant

After the switch, sender is filled from the selected organization profile only when:

organizationId is present
senderId is missing or empty
sender is missing or an empty array

Examples:

organizationId only: tenant switches and sender is filled from the organization profile
organizationId + senderId: tenant switches, then senderId decides sender
organizationId + sender: tenant switches, but explicit sender stays

senderId and receiverId

senderId and receiverId run before consignment templates. If a lookup succeeds, the resolver rewrites the full sender or receiver payload.

Important details:

the current fill pipe resolves these fields by quick_id
unresolved values are normalized to null
a successful lookup replaces any earlier inline party payload

Examples:

senderId + sender: resolved senderId wins
receiverId + receiver: resolved receiverId wins
invalid senderId + sender: senderId becomes null and inline sender remains

Note

The validation rule accepts numeric address id or quick_id for senderId and receiverId, but the current fill pipe resolves them by quick_id. In practice these fields should use quick_id.

senderAddressId and receiverAddressId

senderAddressId and receiverAddressId are separate from senderId and receiverId.

Behavior:

lookup is done in the tenant address book
lookup accepts numeric address id or quick_id
successful lookup replaces the full sender or receiver payload
receiverAddressId can also fill preNoticeEmail, preNoticeSMS, and deliveryInstructions
senderAddressId can also fill pickupInstructions

Because these run later than senderId and receiverId, they override earlier party resolution.

consignmentTemplateId

consignmentTemplateId accepts template id or quick_id. When a template resolves, the request is normalized to the template's real id.

Templates can apply:

explicitly through consignmentTemplateId
implicitly through auto-apply rules using serviceId, isCompany, and in some cases receiver.postcode

Merge rules:

normal mode: request values win and the template fills gaps
override mode: template values win
items and parcels are merged per index using the same precedence
the template can fill missing serviceId

freightPayerId

freightPayerId does not fill sender or receiver. It resolves third-party billing contract context.

Behavior:

requires serviceId
looks up an address-book address by id or quick_id
only fills freightPayer when the address has a carrier contract for that service
builds freightPayer mainly from receiver data plus the resolved customer number

If the request already has:

freightPayer.customerNumber
and freightPayer.type = consignee

that path wins before freightPayerId lookup.

Recommended Usage

use organization ulid or quick_id for organizationId
use quick_id for senderId and receiverId
use senderAddressId and receiverAddressId when you want the address book entry to win late in the pipeline
use consignmentTemplateId for defaults or controlled override behavior
avoid sending multiple resolvers for the same party unless you intentionally want the documented priority order