Field reference

This page is the dictionary for the field objects shared across endpoints: the shipment fields and the nested address, line item, shipping cost, linked shipment, event, and document objects. Endpoint-specific behavior (which fields are required where) lives on each endpoint’s guide and reference page.

Value conventions

Money is a string combining amount and ISO 4217 currency code: "150 SGD", "2491 JPY". Amounts allow up to 2 decimal places.
Measurements are strings combining value and unit: "15 cm", "1.5 kg". Dimensions are converted and stored in centimeters.
Timestamps are ISO 8601; a value without timezone is interpreted as UTC. See timestamps.
Phone numbers use + followed by country calling code and number: +6598765432.
Country can be given as country (a name, resolved through a country identifier) or country_code (ISO 3166-1 alpha-2) — either one.
Identifiers (shipment_id, order_id, document_id, tracking_number) accept A–Z a–z 0–9 _ - . with no spaces (tracking_number also accepts / and requires at least 6 characters including one digit).

Shipment

Field	Type & limits	Description
`shipment_uuid`	UUID	Perform.AI-generated unique identifier. Use it to reference the shipment in other endpoints.
`shipment_id`	string, max 50	Your unique identifier for the shipment. Unique across the account; cannot be changed after creation.
`shipment_reference`	string, max 50	An additional reference; searchable in Parcel Overview.
`additional_reference`	string, max 50	A further reference; searchable in Parcel Overview.
`tracking_number`	string, 6–50	Carrier tracking number. Needed together with an identified carrier to retrieve tracking events.
`carrier_reference`	string, max 50	A carrier reference configured under Settings > Carriers. An unconfigured value is rejected.
`order_uuid`	UUID	Perform.AI-generated order identifier. Preferred over `order_id` if both are sent.
`order_id`	string, max 50	Your order identifier. Creates the order if it doesn’t exist.
`order_reference`	string, max 50	An additional order reference; searchable. Settable only together with a new `order_id`.
`order_source_type`	string, max 500	The type of source the order came from.
`order_source_name`	string, max 500	The name of the order’s source.
`tags`	array of strings, max 100 per tag	Labels for filtering. Stored lowercase.
`notification_email`	array of email addresses, max 100 each	Recipients of tracking email notifications.
`notification_phone`	array of phone numbers, max 30 each	Recipients of tracking SMS notifications.
`tracking_page_reference`	string, max 50	Assigns the shipment to a tracking page for notification branding and tracking links.
`recipient_address`, `sender_address`, `to_address`, `from_address`, `return_address`	Address object	See Address. `to_address`/`from_address` country also populates the shipment’s destination/origin country.
`shipment_value`	money string	Total value of items.
`total_shipping_cost`	money string	Total shipping cost; computed from `shipping_costs` if not provided.
`shipping_costs`	array of objects	See Shipping cost.
`cod_value`	money string	Cash-on-delivery amount.
`payment_type`	string, max 75	Payment method used.
`length`, `width`, `height`	measurement string	Shipment dimensions; stored in cm.
`weight`	measurement string	Shipment weight.
`item_count`	integer ≥ 0	Number of items.
`packaging_type`	string, max 75	Packaging used.
`note`	string, max 500	Free-text note.
`description_of_goods`	string, max 500	Description of the shipment’s contents.
`handling_instructions`	string, max 500	Handling instructions.
`sales_channel`	string, max 100	Sales channel of origin.
`shipping_service`	string, max 50	Carrier shipping service used.
`events`	array of objects	Manual events; see Event.
`linked_shipments`	array of objects	See Linked shipment.
`documents`	array of objects	See Document.
`expected_delivery_from`, `expected_delivery_to`	timestamp	Expected delivery window. `_to` requires `_from`.
`line_items`	array of objects	See Line item.
`additional_info`	object, max 50 per key / 150 per value	Your custom fields for the shipment.

Address

Field	Type & limits	Description
`address_name`	string, max 50	Name or description of the address.
`location_type`	string, max 50	Type of location.
`entity_reference`	string, max 50	Reference for the entity behind the address (customer, merchant, supplier…).
`salutation`	string, max 50	Salutation for the person, if any.
`first_name`	string, max 150	First or full name.
`last_name`	string, max 150	Last name.
`line1`, `line2`, `line3`	string, max 150 each	Address lines.
`street_name`	string, max 500	Street name, when you keep it separate from the address lines.
`house_number`	string, max 50	House or building number, when kept separate.
`city`	string, max 75	City.
`postal_code`	string, max 25	Postal code.
`state_or_province`	string, max 75	State or province.
`region`	string, max 75	Region.
`country`	string, max 75	Country name; resolved and stored as the identified name. Provide this or `country_code`.
`country_code`	ISO 3166-1 alpha-2	Two-letter country code. Provide this or `country`.
`email`	email, max 100	Contact email for the address. Not subscribed to notifications — use `notification_email` for that.
`phone`	phone number, max 30	Contact phone. Not subscribed to notifications — use `notification_phone`.
`fax`	string, max 16	Fax number: `+` followed by up to 15 digits.
`company`	string, max 150	Company name.
`tax_id`	string, max 100	Tax ID of the person or entity.

Carriers often enforce stricter limits than this API at booking and label generation — 35 characters per address line is common. Keeping address lines short avoids failures downstream even when the API accepts the value.

Line item

Field	Type & limits	Description
`product_name`	string, max 500	Product name.
`product_id`	string, max 50	Your product identifier.
`product_reference`	string, max 50	Additional product reference.
`product_category`	string, max 500	Product category.
`product_description`	string, max 500	Product description.
`product_origin_country_code`	ISO 3166-1 alpha-2	Country of origin.
`hs_code`	string, max 20	Harmonized System code.
`customs_description`	string, max 500	Description for customs.
`quantity`	integer, 1–1,000,000 (default 1)	Quantity of this item.
`product_image_url`	URL, max 1024	Product image (JPG/PNG/GIF up to 5 MB; stored at up to 1 MB, 1024×1024).
`product_url`	URL, max 1024	Product page.
`product_weight` + `product_weight_unit`	decimal + unit	Weight per unit.
`line_item_weight` + `line_item_weight_unit`	decimal + unit	Weight of the line.
`currency_code`	ISO 4217	Currency for the cost fields. Must match across all line items in a shipment.
`product_cost`, `subtotal_cost`, `discount_amount`, `tax_amount`, `misc_cost`, `total_price`	decimal ≥ 0	Cost breakdown per line.
`return_id`	string, max 50	Return this line item belongs to, if any.
`return_reason`	string, max 512	Reason the item is being returned.
`additional_info`	object, max 50 per key / 150 per value	Your custom fields for the line item.

Shipping cost

Field	Type & limits	Description
`name`	string	Name of the cost component. Required per entry.
`reference`	string	Reference for the cost component.
`unit_quantity`	number > 0	Unit count; multiplied with `unit_cost` to form `total_cost`.
`unit_cost`	money string	Price per unit.
`total_cost`	money string	Total for the component — provide it directly, or `unit_cost` + `unit_quantity`.

All entries in one request must use the same currency.

Linked shipment

Field	Type & limits	Description
`tracking_number`	string, 6–50. Required	Tracking number of the linked shipment.
`carrier_reference`	string. Required	Configured carrier reference for the linked shipment.

Events retrieved for a linked shipment are incorporated into the main shipment’s events.

Event

Field	Type & limits	Description
`description`	string, max 250	Event description. Provide this or `standard_key`; if both, `standard_key` wins and `description` is ignored (returns a 299 warning).
`standard_key`	string, max 5	A Perform.AI standard event key. The key list is available from your account team.
`date_time`	timestamp	Defaults to the current time (UTC) when omitted.
`location.place`	string, max 250	Event location. Required if `location` is provided.
`additional_info`	object, max 50 per key / 150 per value	Custom fields for the event.

Document

Field	Type & limits	Description
`document_id`	string, max 50	Your unique ID for the document within the shipment.
`name`	string, max 50	Document name (not unique).
`type`	string, max 25	Document type, e.g. invoice, customs declaration.
`file_format`	string, max 25	File format, e.g. pdf.
`link`	URL	Where Perform.AI downloads the document from — must be public, IP-allowlisted, or time-expiring. An undownloadable link is not stored.
`created_date`	timestamp	Defaults to the current time (UTC) when omitted.
`additional_info`	object, max 50 per key / 150 per value	Custom fields for the document.

Get Started

Core Concepts

API Essentials

Shipments

Booking & Labels

Returns

Events

Webhooks

Checkout

Customer Experience

Integrations

Resources

Value conventions

Shipment

Address

Line item

Shipping cost

Linked shipment

Event

Document

​Value conventions

​Shipment

​Address

​Line item

​Shipping cost

​Linked shipment

​Event

​Document

Value conventions

Shipment

Address

Line item

Shipping cost

Linked shipment

Event

Document