> ## Documentation Index > Fetch the complete documentation index at: https://developers.perform.ai/llms.txt > Use this file to discover all available pages before exploring further. # Field reference > Every shared field used across the Perform.AI Public API — types, character limits, and formats. 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](/essentials/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](#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](#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](#event). | | `linked_shipments` | array of objects | See [Linked shipment](#linked-shipment). | | `documents` | array of objects | See [Document](#document). | | `expected_delivery_from`, `expected_delivery_to` | timestamp | Expected delivery window. `_to` requires `_from`. | | `line_items` | array of objects | See [Line item](#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. |