{ "openapi": "3.0.1", "info": { "title": "PRO SHIPPING CORE API", "description": "# Introduction\nHere you will find requirements for integrating with PRO SHIPPING CORE API.\n\nThe documentation specifically covers how the API can be used by business customers to conduct shipping activity with available carriers and provides the technical information to build this integration. The API allows customers to create and manage shipments, produce labels, customs documentation, and collection manifests, retrieve reference data such as carriers and countries, and maintain their own data such as shipping account details.\n\nIntersoft API is a fully RESTful service implemented using JSON messaging. You, as the customer are responsible for sending JSON messages and for maintaining the capability of receiving JSON messages in the format described in this specification. Request and response examples for each API service are included in this specification.\n\n# Authentication\n\nThe PRO SHIPPING CORE API uses OAuth2 authentication.\n\nTo request the authorization token you need to create API credentials (Client ID and Secret) on the system first. If you have not done it already, log into your account and go to API Credentials or follow the link [add a link here with the path to the API Credentials menu]. Use the credentials to retrieve the authorization token.\n\nNote: Make sure you copy the Secret and keep it secure as you won't be able to view it again on the system.\n\n\n", "version": "v4.0", "x-logo": { "url": "/Content/images/redoc-logo.png", "altText": "ReDoc" } }, "servers": [ { "url": "https://api.proshipping.net/", "description": "Pro Shipping Server" } ], "paths": { "/v4/ShippingAccounts": { "get": { "tags": [ "Shipping Accounts" ], "summary": "Get Accounts", "description": "Retrieves a list of all shipping accounts for all carriers created on your customer account.", "parameters": [ { "name": "searchTerm", "in": "query", "description": "A string representing the term or keywords used to filter shipping accounts results. This can be an account name or identifier that you are interested in to narrow down the list based on the input.", "schema": { "type": "string" } }, { "name": "pageSize", "in": "query", "description": "An integer that defines the number of account entries (record) returned per page in the response. For instance, if **pageSize** is set to 20, the API will return up to 20 accounts in each response.\r
\r
***Note**: By default, this value is set to 100.*", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "default": 100 } }, { "name": "pageNumber", "in": "query", "description": "An integer indicating the specific page of results to retrieve, allowing for pagination of larger datasets. For example, if **pageNumber** is set to 3, the API will return the results corresponding to the third page of accounts based on the specified **pageSize**.\r
\r
***Note**: By default, this value is set to 1.*", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "default": 1 } }, { "name": "sortBy", "in": "query", "description": "A string specifying the field by which to organise the search results. For instance, \"Name\" could be used to sort locations alphabetically, arranging the results in a more user-friendly order.\r
\r
***Note**: By default, this value is set to Name.*", "schema": { "$ref": "#/components/schemas/ShippingAccountsSortBy" } }, { "name": "sortDir", "in": "query", "description": "A string indicating the direction in which to sort the results, typically set to \"ascending\" or \"descending.\" For example, setting **sortDir** to \"Ascending\" while using \"Name\" as **sortBy** would arrange the locations from A to Z.\r
\r
***Note**: By default, this value is set to Ascending.*", "schema": { "$ref": "#/components/schemas/OrderDirection" } } ], "responses": { "200": { "description": "Returns a paged list of shipping accounts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShippingAccountsPagedResponse" } } } }, "400": { "description": "Invalid request response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "Message": "Invalid Request", "Errors": [ { "Message": "The page size must be 1 or greater.", "Cause": "pageSize", "ErrorCode": "E1002" }, { "Message": "The page number must be 1 or greater.", "Cause": "pageNumber", "ErrorCode": "E1002" } ] } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" }, "403": { "description": "Forbidden" } }, "security": [ { "oauth2": [ ] } ] } }, "/v4/ShippingAccounts/{carrierCode}/{shippingAccountId}/unlinkLocations": { "put": { "tags": [ "Shipping Accounts" ], "summary": "Unlink Locations", "description": "Remove the association between particular shipping locations from a specific carrier shipping account.", "parameters": [ { "name": "carrierCode", "in": "path", "description": "A unique identifier for the carrier associated with the shipping account. This code is typically alphanumeric and helps in identifying the specific carrier linked to the shipping account.", "required": true, "schema": { "type": "string" } }, { "name": "shippingAccountId", "in": "path", "description": "A unique identifier for each shipping account assigned by the system or you (alias), allowing for efficient reference and management of individual accounts within the system.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Shipping Locations\r\nThe locations to remove from the account.\r\nAt least one location must be provided.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ShippingLocationIdRequest" } } } } }, "responses": { "200": { "description": "The location(s) have been unlinked from the shipping account successfully." }, "404": { "description": "The shipping account or location was not found." }, "400": { "description": "Invalid request response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "Message": "Invalid Request", "Errors": [ { "Message": "There must be at least one location associated with the shipping account. You cannot unlink all shipping locations.", "Cause": "ShippingLocationIds", "ErrorCode": "E1002" } ] } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" }, "403": { "description": "Forbidden" } }, "security": [ { "oauth2": [ ] } ] } }, "/v4/ShippingAccounts/{carrierCode}/{shippingAccountId}": { "delete": { "tags": [ "Shipping Accounts" ], "summary": "Delete Account", "description": "Delete an existing shipping account from the system that is no longer required.", "parameters": [ { "name": "carrierCode", "in": "path", "description": "A unique identifier for the carrier associated with the shipping account. This code is alphanumeric and helps in identifying the specific carrier linked to the shipping account.", "required": true, "schema": { "type": "string" } }, { "name": "shippingAccountId", "in": "path", "description": "A unique identifier for each shipping account assigned by the system (**shippingAccountId**) or you (**AccountAlias**), allowing for efficient reference and management of individual accounts within the system.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The shipping account was deleted successfully." }, "404": { "description": "The shipping account was not found." }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" }, "403": { "description": "Forbidden" } }, "security": [ { "oauth2": [ ] } ] } }, "/v4/shipments/{shippingLocationId}": { "get": { "tags": [ "Shipments" ], "summary": "Get Shipments", "description": "Retrieve a list of shipments for the specified shipping location in a given time period. With this endpoint, you can filter and view details of your shipments based on various criteria, such as status, date ranges, and other parameters.", "parameters": [ { "name": "shippingLocationId", "in": "path", "description": "A unique identifier for the shipping location assigned by the system or by you (alias), allowing users to reference and manage specific locations effectively.\r
\r
***Note**: To get the shipments for a particular shipping location, you can filter this value by the shipping location ID. If the **ShippingLocationId** is not provided, then the response will return shipments for all shipping locations.*", "required": true, "schema": { "type": "string" } }, { "name": "shippingAccountId", "in": "query", "description": "A unique identifier for each shipping account assigned by the system or you (alias), allowing for efficient reference and management of individual accounts within the system.\r
\r
***Note**: To get the shipments for a particular shipping account, you can filter this value by the shipping account ID. If the **ShippingAccountId** is not provided, then the response will return shipments for all shipping accounts.*", "schema": { "maxLength": 36, "type": "string" } }, { "name": "carrierCode", "in": "query", "description": "A unique identifier for the carrier associated with the shipping account. This code is typically alphanumeric and helps in identifying the specific carrier linked to the shipping account.\r
\r
***Note**: If both the shipping account ID and the carrier code are provided, then the value sent in the **carrierCode** field is ignored and the carrier associated with the shipping account is used instead.*", "schema": { "maxLength": 10, "type": "string" } }, { "name": "status", "in": "query", "description": "Indicates the current state of a shipment. You can filter your shipments using any of the following statuses: \r
• **Created**: The shipment has been initiated but not processed.\r
• **OnHold**: The shipment is temporarily paused for various reasons.\r
• **Cancelled**: The shipment has been cancelled and will not proceed.\r
• **ReadyToPrint**: The shipment is prepared for label printing.\r
• **LabelPrinted**: The shipping label has been generated and printed.\r
• **Confirmed**: The shipment has been confirmed and is set for processing.\r
• **Picked**: The package has been picked up for delivery.", "schema": { "$ref": "#/components/schemas/GetShipmentsStatusType" } }, { "name": "destinationCountryCode", "in": "query", "description": "An abbreviation representing the destination country for the shipment, following the ISO 3166-1 alpha-2 standard, for example, \"GB\" for the United Kingdom.", "schema": { "maxLength": 2, "minLength": 2, "type": "string" } }, { "name": "dateFrom", "in": "query", "description": "A timestamp indicating the start date for filtering shipments in the query. This helps users retrieve shipments created or processed after this specified date.\r
\r
***Note**: The date must be in the YYYY-MM-DD format. If the date is not provided, then the value in this field defaults to the current (today's) date.*", "schema": { "type": "string", "format": "date" } }, { "name": "dateTo", "in": "query", "description": "A timestamp indicating the end date for filtering shipments in the query. This allows users to view shipments processed up to this specified date.\r
\r
***Note**: The date must be in the YYYY-MM-DD format. If the date is not provided, then the value in this field defaults to the current (today's) date.*", "schema": { "type": "string", "format": "date" } }, { "name": "pageSize", "in": "query", "description": "An integer that defines the number of shipments returned per page in the response. For instance, if **pageSize** is set to 20, the API will return up to 20 shipments in each response.\r
\r
***Note**: By default, this value is set to 100.*", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "default": 100 } }, { "name": "pageNumber", "in": "query", "description": "An integer indicating the specific page of results to retrieve, allowing for pagination of larger datasets. For example, if **pageNumber** is set to 3, the API will return the results corresponding to the third page of shipments based on the specified **pageSize**.\r
\r
***Note**: By default, this value is set to 1.*", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "default": 1 } } ], "responses": { "200": { "description": "Returns a list of shipments.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipmentsPagedResponse" }, "example": { "Shipments": [ { "ShippingAccountId": "310d6beb-ae36-40e7-918f-f92100c1719d", "ShipmentId": "9d171814-2abc-4c13-8c78-a3330a5cc0ee", "TrackingNumber": "TT000000005GB", "BarcodeNumber": "4C0069786000000000B1F", "Reference1": "OrderRef56", "ShipmentDate": "2026-09-05", "Status": "Created", "ManifestNumber": "ISH2802532", "ContainerId": "South East 1234", "Carrier": "RM", "DestinationCountryCode": "GB", "LastUpdatedBy": "User A", "LastUpdatedDateUtc": "2026-09-05T07:48:01.084Z" }, { "ShippingAccountId": "310d6beb-ae36-40e7-918f-f92100c1719d", "ShipmentId": "9d171814-2abc-4c13-8c78-a3330a5cc0ee", "TrackingNumber": "", "BarcodeNumber": "", "Reference1": "OrderRef57", "ShipmentDate": "2026-09-05", "Status": "LabelPrinted", "ManifestNumber": "", "ContainerId": "", "Carrier": "RM", "DestinationCountryCode": "GB", "LastUpdatedBy": "User B", "LastUpdatedDateUtc": "2026-09-05T07:48:01.084Z" } ], "TotalCount": 2 } } } }, "400": { "description": "Invalid request response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "Message": "Invalid Request", "Errors": [ { "Message": "The page size must be 1 or greater.", "Cause": "pageSize", "ErrorCode": "E1002" }, { "Message": "The page number must be 1 or greater.", "Cause": "pageNumber", "ErrorCode": "E1002" } ] } } } }, "404": { "description": "The shipping location was not found." }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" }, "403": { "description": "Forbidden" } }, "security": [ { "oauth2": [ ] } ] } }, "/v4/shipments/printDocument/{carrierCode}/{shipmentId}": { "post": { "tags": [ "Shipments" ], "summary": "Print Document", "description": "Generate and print various shipping-related documents required for international shipping and customs clearance. With this endpoint, you can specify details of the document you wish to print, submit necessary information, and receive a formatted document in return, typically in the PDF format.", "parameters": [ { "name": "carrierCode", "in": "path", "description": "A unique identifier for the carrier associated with the shipping account. This code is typically alphanumeric and helps in identifying the specific carrier linked to the shipping account.", "required": true, "schema": { "type": "string" } }, { "name": "shipmentId", "in": "path", "description": "A unique identifier for the specific shipment for which the document is being printed. This ID is used to reference and track specific shipments within the system.\r
\r
***Note**: This ID can be a tracking/barcode number.*", "required": true, "schema": { "maxLength": 36, "minLength": 1, "type": "string" } } ], "requestBody": { "description": "Print Document Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrintDocumentRequest" } } } }, "responses": { "200": { "description": "Returns the specified document for the given shipment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrintDocumentResponse" } } } }, "400": { "description": "Invalid request response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "Message": "Invalid Request", "Errors": [ { "Message": "The number of copies must be between 1 and 5.", "Cause": "numCopies", "ErrorCode": "E1002" } ] } } } }, "404": { "description": "The shipment was not found." }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" }, "403": { "description": "Forbidden" } }, "security": [ { "oauth2": [ ] } ] } }, "/v4/shipments/commercialInvoice/{carrierCode}/{shipmentId}": { "put": { "tags": [ "Shipments" ], "summary": "Add Commercial Invoice", "description": "Add Commercial Invoices associated with your shipments as in the base64-encoded PDF format.", "parameters": [ { "name": "carrierCode", "in": "path", "description": "A unique identifier for this carrier. This code is typically alphanumeric and serves as a reference to distinguish between various carriers within the system.", "required": true, "schema": { "maxLength": 10, "minLength": 1, "type": "string" } }, { "name": "shipmentId", "in": "path", "description": "Shipment Id\r
The Shipment Id may be an id or a tracking/barcode number.", "required": true, "schema": { "maxLength": 36, "minLength": 1, "type": "string" } } ], "requestBody": { "description": "Commercial Invoice Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommercialInvoiceRequest" } } } }, "responses": { "200": { "description": "The Commercial Invoice has been successfully linked to the Shipment Id." }, "400": { "description": "Invalid request response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "Message": "Invalid Request", "Errors": [ { "Message": "The document can not be converted to a PDF", "Cause": "Document", "ErrorCode": "E1002" } ] } } } }, "404": { "description": "The shipment was not found." }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" }, "403": { "description": "Forbidden" } }, "security": [ { "oauth2": [ ] } ] } }, "/v4/shipments/status": { "put": { "tags": [ "Shipments" ], "summary": "Update Status", "description": "Modify the current status of one or more shipments in the system. With this endpoint, you can update the status of specified shipments, such as placing them on hold, cancelling them, releasing them for delivery, or marking them as picked.", "requestBody": { "description": "Update Status Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateStatusRequest" }, "example": { "Status": "Cancel", "Reason": "Order Cancelled", "ShipmentIds": [ "TT123456783GB", "e3239e85-ddf8-4323-9064-b83c38eff927", "072d80e4-8f9f-42e4-9c03-6b81a3597ce6", "e9848731-e65c-4a9b-a86d-bbbbfbe7d93a", "d8d6ca51-a0d1-4dc1-845d-f24ea2dc117d", "TT382749386GB", "3A00697860000000B6824" ] } } } }, "responses": { "200": { "description": "All shipments were updated successfully." }, "400": { "description": "Invalid request response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "Message": "Invalid Request", "Errors": [ { "Message": "The reason is required when cancelling shipments.", "Cause": "Reason", "ErrorCode": "E1001" }, { "Message": "The shipment has already been manifested and cannot be cancelled.", "Cause": "ShipmentIds[7]", "ErrorCode": "E1003" }, { "Message": "The shipment does not exist.", "Cause": "ShipmentIds[10]", "ErrorCode": "E1004" } ] } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" }, "403": { "description": "Forbidden" } }, "security": [ { "oauth2": [ ] } ] } }, "/v4/shipments/defer": { "put": { "tags": [ "Shipments" ], "summary": "Defer Shipments", "description": "Postpone the processing or delivery of specific shipments. With this endpoint, you can specify which shipments you would like to defer and provide new shipment dates, streamlining the logistics workflow when shipments cannot proceed as planned due to issues, such as delays, scheduling conflicts, or customer requests.\r
\r
Before deferring a shipment, bear in mind the following:\r
\r
• The shipment can be deferred by a maximum of 28 days from the date of the request.\r
• The shipment can only be deferred before it has been manifested.\r
• The maximum allowable defer requests per call is 99.", "requestBody": { "description": "Defer shipment requests", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DeferShipmentRequest" } }, "example": [ { "ShipmentId": "AD123456783GB", "ShipmentDate": "2026-09-10" }, { "ShipmentId": "e3239e85-ddf8-4323-9064-b83c38eff927", "ShipmentDate": "2026-09-15" } ] } } }, "responses": { "200": { "description": "All shipments were deferred successfully." }, "400": { "description": "Invalid request response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "Message": "Invalid Request", "Errors": [ { "Message": "The Shipment Id is required.", "Cause": "[2].ShipmentId", "ErrorCode": "E1001" }, { "Message": "The shipment is in an invalid state to be deferred.", "Cause": "[7].ShipmentId", "ErrorCode": "E1003" }, { "Message": "The shipment does not exist.", "Cause": "[10].ShipmentId", "ErrorCode": "E1004" } ] } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" }, "403": { "description": "Forbidden" } }, "security": [ { "oauth2": [ ] } ] } }, "/v4/addresses": { "get": { "tags": [ "Address Book" ], "summary": "Get Addresses", "description": "Retrieve a list of shipping addresses for your customer account in the system. With this endpoint, you can get specific addresses based on various parameters, providing pagination and sorting features to help manage results effectively.", "parameters": [ { "name": "searchTerm", "in": "query", "description": "A string representing the term or keywords used to filter the search results for the addresses.This parameter helps you find specific addresses by different attributes.", "schema": { "type": "string" } }, { "name": "pageSize", "in": "query", "description": "An integer that defines the number of address records returned per page in the response. For instance, if **pageSize** is set to 20, the API will return up to 20 addresses in each response.

***Note:** By default, this value is set to 100*", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "default": 100 } }, { "name": "pageNumber", "in": "query", "description": "An integer indicating the specific page of results to retrieve, allowing for pagination of larger datasets. For example, if **pageNumber** is set to 3, the API will return the results corresponding to the third page of addresses based on the specified **pageSize**.

***Note:** By default, this value is set to 1.*", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "default": 1 } }, { "name": "sortBy", "in": "query", "description": "A string specifying the field by which to organise the search results. For instance, \"ContactName\" could be used to sort addresses alphabetically, arranging the results in a more user-friendly order.\r
\r
***Note:** By default, this field is set to ContactName.*", "schema": { "$ref": "#/components/schemas/AddressBookSortBy" } }, { "name": "sortDir", "in": "query", "description": "A string indicating the direction in which to sort the results, typically set to \"ascending\" or \"descending.\" For example, setting **sortDir** to \"Ascending\" while using \"ContactName\" as **sortBy** would arrange the addresses from A to Z.\r
\r
***Note:** By default, this field is set to Ascending.*", "schema": { "$ref": "#/components/schemas/OrderDirection" } } ], "responses": { "200": { "description": "Returns a list of addresses.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressBookPagedResponse" } } } }, "400": { "description": "Invalid request response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "Message": "Invalid Request", "Errors": [ { "Message": "The page size must be 1 or greater.", "Cause": "pageSize", "ErrorCode": "E1002" }, { "Message": "The page number must be 1 or greater.", "Cause": "pageNumber", "ErrorCode": "E1002" } ] } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" }, "403": { "description": "Forbidden" } }, "security": [ { "oauth2": [ ] } ] }, "post": { "tags": [ "Address Book" ], "summary": "Add Address", "description": "Add a new address to your system's address book. With this endpoint, you can create a new address and submit the necessary details of that address, enabling the system to store the information in the Address Book for later use in the Create Shipment requests.", "requestBody": { "description": "Address Book details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddAddressBook" } } } }, "responses": { "200": { "description": "The address book was added successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddAddressBookResponse" } } } }, "400": { "description": "Invalid request response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "Message": "Invalid Request", "Errors": [ { "Message": "The Line 1 maximum length is 50 characters.", "Cause": "Line 1", "ErrorCode": "E1002" } ] } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" }, "403": { "description": "Forbidden" } }, "security": [ { "oauth2": [ ] } ] } }, "/v4/addresses/{addressId}": { "delete": { "tags": [ "Address Book" ], "summary": "Delete Address", "description": "Delete an address from the Address Book that is obsolete or no longer required in your shipment requests.", "parameters": [ { "name": "addressId", "in": "path", "description": "A unique identifier assigned by the system (ID) or by you (alias) of the address that is being deleted. This information ensures that each address can be distinctly referenced and managed within the system.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The address book has been successfully deleted." }, "404": { "description": "The address book does not exist." }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" }, "403": { "description": "Forbidden" } }, "security": [ { "oauth2": [ ] } ] }, "get": { "tags": [ "Address Book" ], "summary": "Get Address", "description": "Retrieves detailed information on a specific address record stored in the system's address book. With this endpoint, you can query for an address using a unique identifier and get the relevant details associated with it.", "parameters": [ { "name": "addressId", "in": "path", "description": "A unique identifier for each address record assigned by the system (ID) or by you (alias). This information ensures that each address is distinctly referenced and managed within the system.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns the details of a address book.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressBookList" } } } }, "404": { "description": "The address book does not exist." }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" }, "403": { "description": "Forbidden" } }, "security": [ { "oauth2": [ ] } ] }, "put": { "tags": [ "Address Book" ], "summary": "Update Address", "description": "Modify the details of an existing address record in the system's address book. With this endpoint, you can submit updated information for a specific address, ensuring that it reflects the most current and accurate data.", "parameters": [ { "name": "addressId", "in": "path", "description": "A unique identifier for each existing address record stored in the address book. This information ensures that each address can be distinctly referenced and managed within the system.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Address Book details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAddressBook" } } } }, "responses": { "200": { "description": "The address book was updated successfully." }, "400": { "description": "Invalid request response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "Message": "Invalid Request", "Errors": [ { "Message": "The Line 1 maximum length is 50 characters.", "Cause": "Line 1", "ErrorCode": "E1002" } ] } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" }, "403": { "description": "Forbidden" } }, "security": [ { "oauth2": [ ] } ] } }, "/v4/carriers": { "get": { "tags": [ "Carriers" ], "summary": "Get Carriers", "description": "Retrieves a list of available carriers on the system along with their unique codes and descriptive details, enabling users to view and select from different carriers.", "responses": { "200": { "description": "Returns a list of carriers.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Carrier" } } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" }, "403": { "description": "Forbidden" } }, "security": [ { "oauth2": [ ] } ] } }, "/v4/carriers/{carrierCode}": { "get": { "tags": [ "Carriers" ], "summary": "Get Carrier", "description": "Retrieves detailed information about a specific carrier, including its services, logo, and operational information, based on the provided carrier code.", "parameters": [ { "name": "carrierCode", "in": "path", "description": "A unique identifier for this carrier. This code is typically alphanumeric and serves as a reference to distinguish between various carriers within the system.", "required": true, "schema": { "maxLength": 10, "minLength": 1, "type": "string" } } ], "responses": { "200": { "description": "Returns the details of a carrier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CarrierDetailed" } } } }, "404": { "description": "The carrier does not exist or is not enabled." }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" }, "403": { "description": "Forbidden" } }, "security": [ { "oauth2": [ ] } ] } }, "/v4/carriers/{carrierCode}/services": { "get": { "tags": [ "Carriers" ], "summary": "Get Carrier Services", "description": "Retrieves a list of services offered by a specific carrier, giving users insight into the various available transportation and logistics options. The response includes the service code and description for each carrier service, along with the carrier service levels returned in the **CarrierSpecifics** object (if available).", "parameters": [ { "name": "carrierCode", "in": "path", "description": "A unique identifier for this carrier. This code is typically alphanumeric and serves as a reference to distinguish between various carriers within the system.", "required": true, "schema": { "maxLength": 10, "minLength": 1, "type": "string" } }, { "name": "shippingAccountId", "in": "query", "description": "PRO SHIPPING Shipping Account Id (assigned by PRO SHIPPING) or Alias (assigned by you). Include this if you want to only get the services for your specific shipping account.", "schema": { "maxLength": 36, "type": "string" } } ], "responses": { "200": { "description": "Returns a list of services.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CarrierService" } } } } }, "404": { "description": "The carrier does not exist or is not enabled or shipping account is not valid/don't exist." }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" }, "403": { "description": "Forbidden" } }, "security": [ { "oauth2": [ ] } ] } }, "/v4/carriers/{carrierCode}/services/{serviceCode}/packageTypes": { "get": { "tags": [ "Carriers" ], "summary": "Get Carrier Service Package Types", "description": "Retrieves the information about package types allowed for a specific carrier service, such as letter, parcel, printed papers, including maximum weight and dimensions.\r
**Note**: *If a carrier does not offer any service package types, then an empty list is returned.*", "parameters": [ { "name": "carrierCode", "in": "path", "description": "A unique identifier for this carrier. This code is typically alphanumeric and serves as a reference to distinguish between various carriers within the system.", "required": true, "schema": { "maxLength": 10, "minLength": 1, "type": "string" } }, { "name": "serviceCode", "in": "path", "description": "A unique identifier for each shipping service provided by the carrier. This code is typically alphanumeric and allows for easy reference and differentiation between various carrier services offered, for example, CRL1, TPM, and so on.", "required": true, "schema": { "maxLength": 10, "minLength": 1, "type": "string" } } ], "responses": { "200": { "description": "Returns a list of package types.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CarrierServicePackageType" } } } } }, "404": { "description": "The carrier does not exist or is not enabled or the service does not exist." }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" }, "403": { "description": "Forbidden" } }, "security": [ { "oauth2": [ ] } ] } }, "/v4/containers": { "get": { "tags": [ "Containers" ], "summary": "Get Containers", "description": "Retrieves a list of shipping containers associated with a specific carrier and shipping location. With this endpoint, you can access information about the containers used for shipments, ensuring effective logistics management.", "parameters": [ { "name": "carrierCode", "in": "query", "description": "A unique identifier for the shipping carrier for which container information is being requested. This code is typically alphanumeric and helps in identifying the specific carrier linked to the container.", "schema": { "type": "string" } }, { "name": "shippingLocationId", "in": "query", "description": "A unique identifier for the shipping location assigned by the system (**ShippingLocationId**) or by you (**LocationAlias**). This parameter allows users to filter the results to only those containers associated with a specific shipping site.", "schema": { "type": "string" } }, { "name": "pageSize", "in": "query", "description": "An integer that defines the maximum number of containers (records) returned per page in the response. For instance, if **pageSize** is set to 20, the API will return up to 20 containers in each response.\r
\r
***Note**: By default, this value is set to 100.*", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "default": 100 } }, { "name": "pageNumber", "in": "query", "description": "An integer indicating the specific page of results to retrieve, allowing for pagination of larger datasets. For example, if **pageNumber** is set to 3, the API will return the results corresponding to the third page of containers based on the specified **pageSize**.\r
\r
***Note**: By default, this value is set to 1.*", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "default": 1 } }, { "name": "sortBy", "in": "query", "description": "A string specifying the field by which to organise the search results. For instance, \"CreateDate\" could be used to sort containers chronologically, arranging the results in a more user-friendly order.\r
\r
***Note**: By default, this field is set to CreatedDateUtc.*", "schema": { "$ref": "#/components/schemas/ContainersSortBy" } }, { "name": "sortDir", "in": "query", "description": "A string indicating the direction in which to sort the results, typically set to \"ascending\" or \"descending.\" For example, setting **sortDir** to \"Ascending\" while using \"CreatedDateUtc\" as **sortBy** would arrange the container from latest creation date to oldest creation date.\r
\r
***Note**: By default, this value is set to Ascending.*", "schema": { "$ref": "#/components/schemas/OrderDirection" } }, { "name": "containerStatus", "in": "query", "description": "Indicates the current status of the container, helping customers quickly find the containers that meet their specific criteria.\r
\r
***Note**: By default, this field is set to Active.*", "schema": { "$ref": "#/components/schemas/ContainerStatusForFiltering" } } ], "responses": { "200": { "description": "Returns a list of containers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContainersPagedResponse" }, "example": { "Containers": [ { "ContainerId": "South East", "ContainerStatus": "Manifested", "CreatedDateUtc": "2026-09-05T07:47:59.648Z", "ShippingLocationId": "93f6d928-9456-434a-9d69-60f3b7dea091", "ShippingLocationAlias": "Northern Warehouse", "TotalWeight": 12.0, "WeightUnitOfMeasure": "KG", "TotalShipments": 2, "TotalPackages": 1 }, { "ContainerId": "South West", "ContainerStatus": "Active", "CreatedDateUtc": "2026-09-04T07:47:59.648Z", "ShippingLocationId": "93f6d928-9456-434a-9d69-60f3b7dea091", "ShippingLocationAlias": "Northern Warehouse", "TotalWeight": 14.0, "WeightUnitOfMeasure": "KG", "TotalShipments": 3, "TotalPackages": 1 } ], "TotalCount": 2 } } } }, "400": { "description": "Invalid request response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "Message": "Invalid Request", "Errors": [ { "Message": "The page size must be 1 or greater.", "Cause": "pageSize", "ErrorCode": "E1002" }, { "Message": "The page number must be 1 or greater.", "Cause": "pageNumber", "ErrorCode": "E1002" } ] } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" }, "403": { "description": "Forbidden" } }, "security": [ { "oauth2": [ ] } ] }, "post": { "tags": [ "Containers" ], "summary": "Add Container", "description": "Create and add new shipping containers to the system for manifesting specific group of shipments. With this endpoint, the system processes the creation of the specified container and associates it with a given carrier and shipping location. This API streamlines logistics management and helps ensure that container data is accurately maintained for shipping operations.", "requestBody": { "description": "Add Container Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddContainerRequest" } } } }, "responses": { "200": { "description": "The container has been successfully created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddContainerResponse" } } } }, "400": { "description": "Invalid request response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "Message": "Invalid Request", "Errors": [ { "Message": "An open container with the containerId already exists for this location.", "Cause": "ContainerId", "ErrorCode": "E1002" } ] } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" }, "403": { "description": "Forbidden" } }, "security": [ { "oauth2": [ ] } ] } }, "/v4/containers/{containerId}": { "get": { "tags": [ "Containers" ], "summary": "Get Container", "description": "Retrieves details of a particular shipping container associated with a specific carrier and shipping location. With this endpoint, you can access information on a specific container used for shipments, ensuring effective logistics management.", "parameters": [ { "name": "containerId", "in": "path", "description": "An identifier assigned by the PRO SHIPPING system or by you (alias) for the shipping container, important for managing cargo and logistics at scale.", "required": true, "schema": { "type": "string" } }, { "name": "returnShipments", "in": "query", "description": "A boolean parameter that, when set to true, modifies the response to include a list of shipments allocated to the container.\r
\r
***Note**: By default, this field is set to false, meaning that only the container's general details will be returned unless specified in the request.*", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Returns the details of the container.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetContainerResponse" }, "examples": { "Without Shipments": { "value": { "ContainerId": "South East", "ContainerStatus": "Active", "CreatedDateUtc": "2026-09-05T07:47:59.745Z", "CarrierCode": "RM", "ShippingLocationId": "93f6d928-9456-434a-9d69-60f3b7dea091", "ShippingLocationAlias": "Northern Warehouse", "TotalWeight": 12.0, "WeightUnitOfMeasure": "KG", "TotalShipments": 2, "TotalPackages": 1 } }, "With Shipments": { "value": { "ContainerId": "South East", "ContainerStatus": "Manifested", "ManifestNumbers": [ "COS0000016" ], "CreatedDateUtc": "2026-09-05T07:47:59.745Z", "CarrierCode": "RM", "ShippingLocationId": "93f6d928-9456-434a-9d69-60f3b7dea091", "ShippingLocationAlias": "Northern Warehouse", "TotalWeight": 12.0, "WeightUnitOfMeasure": "KG", "TotalShipments": 2, "TotalPackages": 1, "Shipments": [ { "TrackingNumber": "TT000860906GB", "BarcodeNumber": "4C0069786000000014AC0", "Reference1": "OrderRef71", "ManifestNumber": "COS0000016" } ] } } } } } }, "404": { "description": "The container does not exist." }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" }, "403": { "description": "Forbidden" } }, "security": [ { "oauth2": [ ] } ] }, "put": { "tags": [ "Containers" ], "summary": "Add/Remove Shipments", "description": "Add one or more shipments to a specific shipping container or remove the shipments from the container. With this endpoint, you can update the container's contents by adding new shipments or removing the existing ones, facilitating optimised logistics management and accurate tracking of goods within containers.\r
\r
***Note**: Once the container has been manifested, the shipments cannot be added or removed.*", "parameters": [ { "name": "containerId", "in": "path", "description": "A unique identifier assigned by the system or by you (alias) for the container to which the shipments are being added or removed. This parameter is necessary for the API to identify which container's contents need to be added or removed.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Update Container Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateContainerRequest" }, "example": { "ShipmentIds": [ "TT123456783GB", "e3239e85-ddf8-4323-9064-b83c38eff927", "072d80e4-8f9f-42e4-9c03-6b81a3597ce6", "e9848731-e65c-4a9b-a86d-bbbbfbe7d93a", "d8d6ca51-a0d1-4dc1-845d-f24ea2dc117d", "TT382749386GB", "3A00697860000000B6824" ], "Mode": "Add" } } } }, "responses": { "200": { "description": "The container has been successfully updated." }, "404": { "description": "The container does not exist." }, "400": { "description": "Invalid request response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "Message": "Invalid Request", "Errors": [ { "Message": "The carrier of the shipment must match the Container carrier.", "Cause": "ShipmentIds[0]", "ErrorCode": "E1002" }, { "Message": "The Shipping Location of the shipment must match the Container Shipping Location.", "Cause": "ShipmentIds[0]", "ErrorCode": "E1002" }, { "Message": "The shipment is not on hold or does not have label printed status.", "Cause": "ShipmentIds[2]", "ErrorCode": "E1003" }, { "Message": "The shipment does not exist.", "Cause": "ShipmentIds[10]", "ErrorCode": "E1004" } ] } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" }, "403": { "description": "Forbidden" } }, "security": [ { "oauth2": [ ] } ] }, "delete": { "tags": [ "Containers" ], "summary": "Delete Container", "description": "Remove a specific shipping container from the system. When this endpoint is requested with the appropriate **ContainerId**, the system processes the deletion of the specified container along with its associated details. This API is essential for managing inventory and ensuring that any obsolete or unnecessary containers are no longer retained in the PRO SHIPPING system.\r
\r
***Note**: If a container is deleted, the shipments inside it remain active but are no longer associated with the container.*", "parameters": [ { "name": "containerId", "in": "path", "description": "A unique identifier assigned by the system or by you (alias) for the container that is to be deleted. This ID is crucial for the API to identify which container the user wishes to remove from the system, ensuring that the deletion action is precise and targeted.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The container has been successfully deleted." }, "404": { "description": "The container does not exist." }, "400": { "description": "Invalid request response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "Message": "Invalid Request", "Errors": [ { "Message": "The container has already been manifested therefore this cannot be deleted. Only containers with Active status can be deleted.", "Cause": "ContainerId", "ErrorCode": "E1003" } ] } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" }, "403": { "description": "Forbidden" } }, "security": [ { "oauth2": [ ] } ] } }, "/v4/manifests/{carrierCode}": { "post": { "tags": [ "Manifests" ], "summary": "Manifest Shipments", "description": "Declare what shipments are ready for dispatch and will be handed over to the carrier. A manifest is a document that summarises the details of the shipments being handed over to the carrier, such as items, weight, and destination information. With this endpoint, you can compile and submit these details for processing, helping to streamline shipping logistics and ensure compliance with carrier requirements.\r
\r
You can manifest the shipments using any of the following parameters:\r
\r
• Shipping location\r
• Shipping account\r
• Shipment status (Picked)\r
• Service code\r
• Container\r
\r
***Note**: If none of the aforementioned parameters are used, then all the shipments in the **LabelPrinted** and **Picked** status will be manifested, excluding the future shipments or the shipments assigned to a container, respectively.*", "parameters": [ { "name": "carrierCode", "in": "path", "description": "A unique identifier representing the shipping carrier with which the shipments are associated. This code is alphanumeric and helps specify which carrier's requirements and formats are being followed when creating the manifest.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Manifest Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManifestRequest" }, "examples": { "Manifest by Shipping Account": { "value": { "ShippingLocationId": "02f6a3f6-68ec-40e2-bb84-4dc052893263", "ShippingAccountId": "349ec6dc-30aa-4f80-9e7f-35dd79e795d8", "Async": false } }, "Manifest by Shipping Account in the background": { "value": { "ShippingLocationId": "57a26d50-0ec8-45ca-95cd-b36c3b2a15c4", "ShippingAccountId": "4d75fba4-32c7-49bb-95a5-8258f63838ab", "Async": true } }, "Manifest by Service": { "value": { "ShippingLocationId": "ce690429-d3eb-4c59-800e-fd6a170e73bc", "ServiceCode": "EXPRESS", "Async": false } }, "Manifest by Service for Shipping Account Only": { "value": { "ShippingLocationId": "61e78089-980f-4a95-87a1-d2dea0827bb4", "ShippingAccountId": "0cd17873-cc95-4bbd-8f55-49954e087fba", "ServiceCode": "EXPRESS", "Async": false } }, "Manifest by Status": { "value": { "ShippingLocationId": "260dc07e-d63b-44f9-98a9-0d00886f3118", "Status": "Picked", "Async": false } }, "Manifest by Container": { "value": { "ShippingLocationId": "5cc1b4a6-e494-4fd3-9483-dc30da12c40f", "ContainerId": "e8f8e30e-d6f9-4df5-918c-f068c4429562", "Async": false } } } } } }, "responses": { "200": { "description": "The shipments have been manifested successfully and all created manifests returned.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ManifestResponse" } } } } }, "400": { "description": "Invalid request response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "Example 1": { "value": { "Message": "There are no shipments ready to be manifested.", "Errors": [] } }, "Example 2": { "value": { "Message": "Invalid Request", "Errors": [ { "Message": "The service code maximum length is 10 characters.", "Cause": "ServiceCode", "ErrorCode": "E1002" }, { "Message": "The shipping account Id does not exist.", "Cause": "ShippingAccountId", "ErrorCode": "E1004" } ] } } } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" }, "403": { "description": "Forbidden" } }, "security": [ { "oauth2": [ ] } ] }, "get": { "tags": [ "Manifests" ], "summary": "Get Manifests", "description": "Retrieves a list of manifests created with a specific carrier. With this endpoint, you can filter manifests based on various criteria, such as shipping locations, accounts, and date ranges, enabling efficient tracking and management of shipment manifests.", "parameters": [ { "name": "carrierCode", "in": "path", "description": "A unique identifier representing the shipping carrier for which the manifests are being queried. This code is alphanumeric and helps specify which carrier's manifests the request pertains to, ensuring that you retrieve relevant data.", "required": true, "schema": { "type": "string" } }, { "name": "shippingLocationId", "in": "query", "description": "A unique identifier assigned by the system (**ShippingLocationId**) or by you (**LocationAlias**) for the shipping location from which the shipments are being manifested. This information is crucial for linking the manifest to the correct shipping point.", "schema": { "maxLength": 100, "type": "string" } }, { "name": "containerId", "in": "query", "description": "An identifier assigned by the PRO SHIPPING system or by you (alias) for the shipping container associated with the shipment, important for managing cargo and logistics at scale.", "schema": { "maxLength": 50, "type": "string" } }, { "name": "shippingAccountId", "in": "query", "description": "A unique identifier assigned by the PRO SHIPPING system (**ShippingAccountId**) or by you (**AccountAlias**) for the shipping account associated with the shipments. This information is important for billing and tracking purposes, connecting the manifest to the correct account. If needed, provide this information if you want to get the manifests by a specific shipping account only.", "schema": { "maxLength": 36, "type": "string" } }, { "name": "dateFrom", "in": "query", "description": "A timestamp indicating the start date for filtering manifests in the query. This allows you to retrieve manifests created after this specified date, providing a way to narrow down the results based on a specified start date.\r
\r
***Note**: The date must be in the YYYY-MM-DD format. By default, this date is set to current (today's) date.*", "schema": { "type": "string", "format": "date" } }, { "name": "dateTo", "in": "query", "description": "A timestamp indicating the end date for filtering manifests in the query. This provides a cutoff date for the results, allowing you to view manifests generated up to this date.\r
\r
***Note**: The date must be in the YYYY-MM-DD format. By default, this date is set to current (today's) date.*", "schema": { "type": "string", "format": "date" } }, { "name": "pageSize", "in": "query", "description": "An integer specifying the maximum number of manifests to return per page in the API's response. This parameter helps control the volume of data returned, enhancing performance and user experience.\r
\r
***Note**: By default, this field is set to 100.*", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "default": 100 } }, { "name": "pageNumber", "in": "query", "description": "An integer indicating which page of results to retrieve, allowing for pagination of larger datasets. In this field, you can specify the page number to access specific segments of the total manifest records.\r
\r
***Note**: By default, this field is set to 1.*", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "default": 1 } } ], "responses": { "200": { "description": "Returns details of the manifests produced or an empty list if none were found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManifestsPagedResponse" } } } }, "404": { "description": "The carrier code was not found." }, "400": { "description": "Invalid request response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "Message": "Invalid Request", "Errors": [ { "Message": "The page size must be 1 or greater.", "Cause": "pageSize", "ErrorCode": "E1002" }, { "Message": "The page number must be 1 or greater.", "Cause": "pageNumber", "ErrorCode": "E1002" } ] } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" }, "403": { "description": "Forbidden" } }, "security": [ { "oauth2": [ ] } ] } }, "/v4/manifests/async/{carrierCode}": { "post": { "tags": [ "Manifests" ], "summary": "Manifest Shipments Async", "description": "Declare what shipments are ready for dispatch and will be handed over to the carrier. A manifest is a document that summarises the details of the shipments being handed over to the carrier, such as items, weight, and destination information. With this endpoint, you can compile and submit these details for processing, helping to streamline shipping logistics and ensure compliance with carrier requirements.\r
\r
You can manifest the shipments using any of the following parameters:\r
\r
• Shipping location\r
• Shipping account\r
• Shipment status (Picked)\r
• Service code\r
• Container\r
\r
***Note**: If none of the aforementioned parameters are used, then all the shipments in the **LabelPrinted** and **Picked** status will be manifested, excluding the future shipments or the shipments assigned to a container, respectively.*", "parameters": [ { "name": "carrierCode", "in": "path", "description": "A unique identifier representing the shipping carrier with which the shipments are associated. This code is alphanumeric and helps specify which carrier's requirements and formats are being followed when creating the manifest.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Manifest Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManifestAsyncRequest" } } } }, "responses": { "200": { "description": "The shipments have been manifested successfully and all created manifests returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManifestShipmentsAsyncResponse" } } } }, "400": { "description": "Invalid request response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "Example 1": { "value": { "Message": "There are no shipments ready to be manifested.", "Errors": [] } }, "Example 2": { "value": { "Message": "Invalid Request", "Errors": [ { "Message": "The service code maximum length is 10 characters.", "Cause": "ServiceCode", "ErrorCode": "E1002" }, { "Message": "The shipping account Id does not exist.", "Cause": "ShippingAccountId", "ErrorCode": "E1004" } ] } } } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" }, "403": { "description": "Forbidden" } }, "security": [ { "oauth2": [ ] } ] } }, "/v4/manifests/manifestStatus/{manifestRequestId}": { "get": { "tags": [ "Manifests" ], "summary": "Get Manifest Request Status", "description": "Retrieves the current status and details of a specific manifest request ID and, optionally, returns base64 encoded images and detailed manifest information.", "parameters": [ { "name": "manifestRequestId", "in": "path", "description": "A unique identifier assigned by the system that specifies the manifest request.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "manifestDetail", "in": "query", "description": "Used to provide full details of the manifest. If set to true, a complete manifest details, including manifest image will be returned. If set to false, then only **manifestRequestId**, **manifestStatus**, and **manifestCount** are returned. \r
\r
***Note**: By default, this field is set to false.*", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "The manifest request status is returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManifestRequestStatusResponse" }, "examples": { "Pending Manifest Request": { "value": { "ManifestRequestId": "00000000-0000-0000-0000-000000000000", "ManifestRequestStatus": "PENDING", "ManifestCount": 0 } }, "Complete Manifest Request": { "value": { "ManifestRequestId": "00000000-0000-0000-0000-000000000000", "ManifestRequestStatus": "COMPLETE", "ManifestCount": 1 } }, "Complete Manifest Request with Details": { "value": { "ManifestRequestId": "00000000-0000-0000-0000-000000000000", "ManifestRequestStatus": "COMPLETE", "ManifestCount": 1, "Manifests": [ { "ManifestImage": "JVBERw0KGgoAAAANSUhEUgAA.....A4QAAAXcCAYAAAB6Q0CbAAAAAXNSR0IArs4", "ManifestNumber": "ISH2802532", "CarrierCode": "RM", "TotalWeight": 1.0, "WeightUnitOfMeasure": "KG", "TotalShipments": 1, "TotalItems": 1, "ManifestDate": "2026-09-05", "CreatedDateUtc": "2026-09-05T07:48:00.521Z", "ShippingLocation": { "ShippingLocationId": "9f9257e1-efde-4485-b5f3-40dcb3b69251", "LocationAlias": "London", "LocationCountry": "GB", "LocationPostcode": "TW20 0HJ" }, "ShippingAccount": { "ShippingAccountId": "e1fb5f18-a4d8-4fa1-a54d-aad46046d0f8", "AccountName": "AccountName", "AccountAlias": "Test", "AccountNumber": "1234567890" } } ] } }, "Failed Manifest Request": { "value": { "ManifestRequestId": "00000000-0000-0000-0000-000000000000", "ManifestRequestStatus": "FAILED", "ManifestCount": 0, "FailedReason": { "Message": "There are no shipments ready to be manifested.", "Errors": [] } } } } } } }, "404": { "description": "The manifest request was not found." }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" }, "403": { "description": "Forbidden" } }, "security": [ { "oauth2": [ ] } ] } }, "/v4/manifests/{carrierCode}/{manifestNumber}": { "get": { "tags": [ "Manifests" ], "summary": "Print Manifest", "description": "Retrieves the base64 encoded printable version of a specified manifest for a particular carrier. With this endpoint, you can obtain a formatted document of the manifest that can be printed for shipping purposes, such as for inclusion in shipment packages or for compliance with logistics requirements.", "parameters": [ { "name": "carrierCode", "in": "path", "description": "A unique identifier for the shipping carrier associated with the manifest being requested. This code is alphanumeric and helps specify which carrier's manifest document should be retrieved, ensuring that you access the correct format and details related to that specific carrier's services.", "required": true, "schema": { "type": "string" } }, { "name": "manifestNumber", "in": "path", "description": "A unique identifier for the manifest that you want to retrieve for printing. This number allows the API to locate and return the specific manifest document requested by you, ensuring that you receive the correct information for your shipping needs.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The manifest, including the PDF, is returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManifestResponse" } } } }, "404": { "description": "The manifest was not found." }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" }, "403": { "description": "Forbidden" } }, "security": [ { "oauth2": [ ] } ] } }, "/v4/manifests/{carrierCode}/{manifestNumber}/shipments": { "get": { "tags": [ "Manifests" ], "summary": "Get Manifest Details", "description": "Retrieves detailed information about a specific shipping manifest associated with a particular carrier. This endpoint provides you with comprehensive data about the shipments included in the manifest, allowing for easier tracking and management of the shipments being delivered.", "parameters": [ { "name": "carrierCode", "in": "path", "description": "A unique identifier for the shipping carrier associated with the manifest for which details are being requested. This code is alphanumeric and helps ensure that the API accurately references the correct carrier's manifest data.", "required": true, "schema": { "type": "string" } }, { "name": "manifestNumber", "in": "path", "description": "A unique identifier for the manifest whose details are being requested. This number allows the API to get the specific information related to that manifest, providing you with accurate data relevant to your shipments.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The manifest, including the shipments manifested, is returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManifestDetailsResponse" } } } }, "404": { "description": "The manifest was not found." }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" }, "403": { "description": "Forbidden" } }, "security": [ { "oauth2": [ ] } ] } }, "/v4/products": { "get": { "tags": [ "Products" ], "summary": "Get Products", "description": "Retrieves a list of products within the system that are available for shipping. With this endpoint, you can search for specific products based on various criteria and that provides relevant product details in the response. It is essential for inventory management, order processing, and logistics planning.", "parameters": [ { "name": "searchTerm", "in": "query", "description": "A string representing the term or keywords used to filter the search results for the products. This parameter helps you find specific products by name, SKU, or other relevant features.", "schema": { "type": "string" } }, { "name": "pageSize", "in": "query", "description": "An integer that defines the number of product records returned per page in the response. For instance, if **pageSize** is set to 20, the API will return up to 20 products in each response.

***Note**: By default, this field is set to 100.*

", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "default": 100 } }, { "name": "pageNumber", "in": "query", "description": "An integer indicating the specific page of results to retrieve, allowing for pagination of larger datasets. For example, if **pageNumber** is set to 3, the API will return the results corresponding to the third page of products based on the specified **pageSize**.

***Note**: By default, this field is set to 1.*

", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "default": 1 } }, { "name": "sortBy", "in": "query", "description": "A string specifying the field by which to organise the search results. For instance, \"Weight\" could be used to sort products on weight values, arranging the results in a more user-friendly order.

***Note**: By default, this field is set to Description.*

", "schema": { "$ref": "#/components/schemas/ProductsSortBy" } }, { "name": "sortDir", "in": "query", "description": "A string indicating the direction in which to sort the results, typically set to \"ascending\" or \"descending.\" For example, setting **sortDir** to \"Ascending\" while using \"Weight\" as **sortBy** would arrange the products from lower to higher weight values.

***Note**: By default, this field is set to Ascending.*

", "schema": { "$ref": "#/components/schemas/OrderDirection" } } ], "responses": { "200": { "description": "Returns a list of products.", "content": { "application/json": { "schema": { "required": [ "Products", "TotalCount" ], "type": "object", "properties": { "Products": { "type": "array", "items": { "required": [ "CurrencyCode", "Description", "SkuCode", "Value", "Weight" ], "type": "object", "properties": { "LastUpdatedDateUtc": { "type": "string", "description": "A timestamp in Coordinated Universal Time (UTC) indicating when the product details were last updated. This helps users understand the recency of the product information.", "format": "date-time", "example": "2022-02-06T16:13:24.010Z" }, "LastUpdatedBy": { "type": "string", "description": "The identifier of the user or system that last modified the product details, ensuring accountability and traceability for updates.", "nullable": true, "example": "User A" }, "SkuCode": { "maxLength": 30, "minLength": 1, "type": "string", "description": "A unique Stock Keeping Unit (SKU) code assigned to the product. This code is essential for tracking inventory, helping users identify specific products easily.", "example": "SKU123" }, "Description": { "maxLength": 255, "minLength": 1, "type": "string", "description": "A brief summary providing details about the product, outlining its features, uses, and any pertinent information that helps users understand the product.\r
\r
***Note**: If you use the data of the stored product in your create shipment requests, then this description will be used as the item description for customs purposes, detailing the specific item being shipped.*", "example": "White Men Large T-shirt" }, "Value": { "maximum": 9999999.99, "minimum": 0.01, "type": "number", "description": "The commercial value of the product. This field is important for inventory valuation and pricing strategies.", "format": "double", "example": 19.99 }, "Weight": { "maximum": 1000000, "minimum": 0.001, "minLength": 1, "type": "string", "description": "The weight of the individual product in the unit of measure specified in the **WeightUnitOfMeasure** field.", "example": "0.5" }, "HSCode": { "maxLength": 13, "minLength": 6, "type": "string", "description": "The Harmonized System (HS) code used by customs to determine potential duties and taxes for the product. This code can be 6, 8, or 13 alphanumeric characters, depending on specific services or destinations. Some countries may also use the HS codes of other character lengths, such as 10 characters.", "nullable": true, "example": "6109100010" }, "CountryOfOrigin": { "maxLength": 2, "minLength": 2, "type": "string", "description": "An abbreviation representing the country where the product was manufactured or produced, following the ISO 3166-1 alpha-2 standard, for example, \"GB\" for the United Kingdom. This information is important for customs declarations and compliance with import/export regulations.", "nullable": true, "example": "GB" }, "CurrencyCode": { "maxLength": 3, "minLength": 3, "type": "string", "description": "An abbreviation representing the 3 letter ISO currency code in which the product's **Value** is expressed (for example, \"GBP\" for British pounds, \"EUR\" for euros). This is essential for financial transactions and international trade.", "example": "GBP" }, "WeightUnitOfMeasure": { "enum": [ "KG", "Grams" ], "type": "string", "description": "The unit of measurement for the weight provided, such as the product's **Weight**, indicating whether the weight is specified in kilograms (KG) or grams (G), ensuring clarity for shipping calculations." }, "ManufactureProductId": { "maxLength": 50, "type": "string", "description": "A unique manufacturer identifier for the item being shipped, for example, proprietary manufacturer code, model number, or internal code. This field is used to reference the shipped item and supports carrier-specific requirements.", "nullable": true }, "StandardisedProductId": { "maxLength": 50, "type": "string", "description": "A globally recognised product identifier for the item being shipped, for example, GTIN, EAN, and UPC. This field is used for standardised item identification and supports carrier-specific requirements for customs and risk assessment.", "nullable": true }, "Hazmat": { "required": [ "Class" ], "type": "object", "properties": { "UNCode": { "maxLength": 4, "minLength": 4, "type": "string", "description": "The United Nations (UN) code assigned to the hazardous material, which denotes its classification for transport. This code is critical for safety and compliance during shipping.", "nullable": true, "example": "1002" }, "ProperShippingName": { "maxLength": 100, "type": "string", "description": "The official name designated for the hazardous material as required by regulations. This name is used to inform handlers of the nature of the hazard during transport.", "nullable": true, "example": "Compressed Air" }, "Class": { "maxLength": 3, "minLength": 1, "type": "string", "description": "The class number of the hazardous material as per UN regulations, indicating the potential risk associated with the product.", "example": "9" }, "Id8000Category": { "type": "string", "description": "A specific category designation used for certain hazardous materials classified under Class 9, providing additional regulatory requirements for handling and transport.\r
Available values are the following:\r
", "nullable": true, "example": "Nail Varnish" }, "Quantity": { "maximum": 5, "type": "number", "description": "The quantity of the hazardous material in the specified **UnitOfMeasure**. This information is vital for compliance with shipping regulations pertaining to hazardous materials.", "format": "double", "nullable": true, "example": 3.5 }, "UnitOfMeasure": { "enum": [ "NONE", "L", "KG" ], "type": "string", "description": "The unit of measurement for the quantity of hazardous material, for example, litres (for liquids) or kilograms (for solids). This provides clarity regarding the amount of hazardous goods present." }, "EmergencyActionCode": { "maxLength": 4, "minLength": 4, "type": "string", "description": "A code providing emergency response instructions for handling hazardous materials during transport.This code is critical for safety and risk management.", "nullable": true, "example": "E012" }, "HazchemNumber": { "maxLength": 3, "minLength": 3, "type": "string", "description": "A number that indicates the type of hazardous material and the precautions necessary for its transport. This helps in emergency situations through quick identification.", "nullable": true }, "SpecialistAdviceContactNumber": { "maxLength": 20, "type": "string", "description": "A contact number for expert advice regarding the handling and transport of hazardous materials. This information is crucial during emergencies or if unusual situations arise.\r
\r
***Note:** If this information is not provided and the hazardous material is used in your **Create Shipment** request, then the contact number will be sent from the customer shipping account record.*", "nullable": true } }, "description": "Specifies the details whether the product is classified as hazardous material. This designation impacts shipping regulations and handling procedures." } }, "description": "Product List" }, "description": "An array containing all products that match the search criteria for the specific page only. Each object contains detailed information about individual products, including attributes necessary for identification and shipping." }, "TotalCount": { "type": "integer", "description": "An integer representing the total number of products that match the search criteria. This count provides users with an overview of how many product records are available based on the filters applied.", "format": "int32", "example": 32 } }, "description": "An array containing all products that match the search criteria for the specific page only. Each object contains detailed information about individual products, including attributes necessary for identification and shipping." }, "examples": { "Products Page": { "value": { "Products": [ { "LastUpdatedDateUtc": "0001-01-01T00:00:00.000Z", "SkuCode": "SKU123", "Description": "White Men Large T-shirt", "Value": 19.99, "Weight": "0.5", "HSCode": "6109100010", "CountryOfOrigin": "GB", "CurrencyCode": "GBP", "WeightUnitOfMeasure": "KG", "ManufactureProductId": "5449000000996", "StandardisedProductId": "4006381333931", "Hazmat": { "UNCode": "1002", "ProperShippingName": "Compressed Air", "Class": "9", "Id8000Category": "Nail Varnish", "Quantity": "3.5", "UnitOfMeasure": "L", "EmergencyActionCode": "E012", "HazchemNumber": "string", "SpecialistAdviceContactNumber": "string" } } ], "TotalCount": 32 } } } } } }, "400": { "description": "Invalid request response.", "content": { "application/json": { "schema": { "required": [ "Errors", "Message" ], "type": "object", "properties": { "Message": { "minLength": 1, "type": "string" }, "Errors": { "type": "array", "items": { "type": "object", "properties": { "Message": { "type": "string", "nullable": true }, "Cause": { "type": "string", "nullable": true }, "ErrorCode": { "type": "string", "description": "

**E1000** - System error
**E1001** - Required field
**E1002** - Invalid field
**E1003** - Invalid action
**E1004** - Item not found
", "nullable": true } } } } } }, "example": { "Message": "Invalid Request", "Errors": [ { "Message": "The page size must be 1 or greater.", "Cause": "pageSize", "ErrorCode": "E1002" }, { "Message": "The page number must be 1 or greater.", "Cause": "pageNumber", "ErrorCode": "E1002" } ] } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" }, "403": { "description": "Forbidden" } }, "security": [ { "oauth2": [ ] } ] }, "post": { "tags": [ "Products" ], "summary": "Add Product", "description": "Add a new product to the system. With this endpoint, you can add product details in the request body, allowing the system to store them in the database, making the product available for further use in your shipment requests.", "requestBody": { "description": "Product details", "content": { "application/json": { "schema": { "required": [ "CurrencyCode", "Description", "SkuCode", "Value", "Weight" ], "type": "object", "properties": { "SkuCode": { "maxLength": 30, "minLength": 1, "type": "string", "description": "A unique Stock Keeping Unit (SKU) code assigned to the product. This code is essential for tracking inventory, helping users identify specific products easily.", "example": "SKU123" }, "Description": { "maxLength": 255, "minLength": 1, "type": "string", "description": "A brief summary providing details about the product, outlining its features, uses, and any pertinent information that helps users understand the product.\r
\r
***Note**: If you use the data of the stored product in your create shipment requests, then this description will be used as the item description for customs purposes, detailing the specific item being shipped.*", "example": "White Men Large T-shirt" }, "Value": { "maximum": 9999999.99, "minimum": 0.01, "type": "number", "description": "The commercial value of the product. This field is important for inventory valuation and pricing strategies.", "format": "double", "example": 19.99 }, "Weight": { "maximum": 1000000, "minimum": 0.001, "minLength": 1, "type": "string", "description": "The weight of the individual product in the unit of measure specified in the **WeightUnitOfMeasure** field.

***Note**: The maximum allowed weight is 1000 grams. For dutiable shipments, the minimum allowed weight is 0.001 Kg.*", "example": "0.5" }, "HSCode": { "maxLength": 13, "minLength": 6, "type": "string", "description": "The Harmonized System (HS) code used by customs to determine potential duties and taxes for the product. This code can be 6, 8, or 13 alphanumeric characters, depending on specific services or destinations. Some countries may also use the HS codes of other character lengths, such as 10 characters.

***Note**: Characters like space and dot are supported.*", "nullable": true, "example": "6109100010" }, "CountryOfOrigin": { "maxLength": 2, "minLength": 2, "type": "string", "description": "An abbreviation representing the country where the product was manufactured or produced, following the ISO 3166-1 alpha-2 standard, for example, \"GB\" for the United Kingdom. This information is important for customs declarations and compliance with import/export regulations.", "nullable": true, "example": "GB" }, "CurrencyCode": { "maxLength": 3, "minLength": 3, "type": "string", "description": "An abbreviation representing the 3 letter ISO currency code in which the product's **Value** is expressed (for example, \"GBP\" for British pounds, \"EUR\" for euros). This is essential for financial transactions and international trade.", "example": "GBP" }, "WeightUnitOfMeasure": { "enum": [ "KG", "Grams" ], "type": "string", "description": "The unit of measurement for the weight provided, such as the product's **Weight**, indicating whether the weight is specified in kilograms (KG) or grams (G), ensuring clarity for shipping calculations.

***Note**: By default, this field is set to KG.*

" }, "ManufactureProductId": { "maxLength": 50, "type": "string", "description": "A unique manufacturer identifier for the item being shipped, for example, proprietary manufacturer code, model number, or internal code.

This field is used to reference the shipped item and supports carrier-specific requirements.", "nullable": true }, "StandardisedProductId": { "maxLength": 50, "type": "string", "description": "A globally recognised product identifier for the item being shipped, for example, GTIN, EAN, and UPC.

This field is used for standardised item identification and supports carrier-specific requirements for customs and risk assessment.", "nullable": true }, "Hazmat": { "required": [ "Class" ], "type": "object", "properties": { "UNCode": { "maxLength": 4, "minLength": 4, "type": "string", "description": "The United Nations (UN) code assigned to the hazardous material, which denotes its classification for transport. This code is critical for safety and compliance during shipping.

***Note**: This field must be populated only for domestic shipments using class 9 dangerous goods.If provided, then **Quantity** and **UnitOfMeasure** must also be specified.*", "nullable": true, "example": "1002" }, "ProperShippingName": { "maxLength": 100, "type": "string", "description": "The official name designated for the hazardous material as required by regulations. This name is used to inform handlers of the nature of the hazard during transport.", "nullable": true, "example": "Compressed Air" }, "Class": { "maxLength": 3, "minLength": 1, "type": "string", "description": "The class number of the hazardous material as per UN regulations, indicating the potential risk associated with the product.", "example": "9" }, "Id8000Category": { "type": "string", "description": "A specific category designation used for certain hazardous materials classified under Class 9, providing additional regulatory requirements for handling and transport.\r
Available values are the following:\r
", "nullable": true, "example": "Nail Varnish" }, "Quantity": { "maximum": 5, "type": "number", "description": "The quantity of the hazardous material in the specified **UnitOfMeasure**. This information is vital for compliance with shipping regulations pertaining to hazardous materials.

***Note**: This field is only required if **UnitOfMeasure** and **UNCode** is specified.*", "format": "double", "nullable": true, "example": 3.5 }, "UnitOfMeasure": { "enum": [ "NONE", "L", "KG" ], "type": "string", "description": "The unit of measurement for the quantity of hazardous material, for example, litres (for liquids) or kilograms (for solids). This provides clarity regarding the amount of hazardous goods present.

***Note**: This field is only required if **Quantity** and **UNCode** is specified.*

" }, "EmergencyActionCode": { "maxLength": 4, "minLength": 4, "type": "string", "description": "A code providing emergency response instructions for handling hazardous materials during transport.This code is critical for safety and risk management.", "nullable": true, "example": "E012" }, "HazchemNumber": { "maxLength": 3, "minLength": 3, "type": "string", "description": "A number that indicates the type of hazardous material and the precautions necessary for its transport. This helps in emergency situations through quick identification.", "nullable": true }, "SpecialistAdviceContactNumber": { "maxLength": 20, "type": "string", "description": "A contact number for expert advice regarding the handling and transport of hazardous materials. This information is crucial during emergencies or if unusual situations arise.\r
\r
***Note:** If this information is not provided and the hazardous material is used in your **Create Shipment** request, then the contact number will be sent from the customer shipping account record.*", "nullable": true } }, "description": "Specifies the details whether the product is classified as hazardous material. This designation impacts shipping regulations and handling procedures." } }, "description": "Product" }, "examples": { "Update": { "value": { "SkuCode": "SKU123", "Description": "White Men Large T-shirt", "Value": 19.99, "Weight": "0.5", "HSCode": "6109100010", "CountryOfOrigin": "GB", "CurrencyCode": "GBP", "WeightUnitOfMeasure": "KG", "ManufactureProductId": "5449000000996", "StandardisedProductId": "4006381333931", "Hazmat": { "UNCode": "1002", "ProperShippingName": "Compressed Air", "Class": "9", "Id8000Category": "Nail Varnish", "Quantity": "3.5", "UnitOfMeasure": "L", "EmergencyActionCode": "E012", "HazchemNumber": "string", "SpecialistAdviceContactNumber": "string" } } } } } } }, "responses": { "200": { "description": "The product was added successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddProductResponse" } } } }, "400": { "description": "Invalid request response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "Message": "Invalid Request", "Errors": [ { "Message": "The product SKU code maximum length is 30 characters.", "Cause": "skuCode", "ErrorCode": "E1002" } ] } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" }, "403": { "description": "Forbidden" } }, "security": [ { "oauth2": [ ] } ] } }, "/v4/products/{skuCode}": { "delete": { "tags": [ "Products" ], "summary": "Delete Product", "description": "Remove a product from the system. With this endpoint, you can permanently delete a specified product from the database, which also ensures that it is no longer available to be used in your shipment requests.", "parameters": [ { "name": "skuCode", "in": "path", "description": "A unique Stock Keeping Unit (SKU) code assigned to the product by you. This code is essential for tracking inventory, helping users identify specific products easily.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The product has been successfully deleted." }, "404": { "description": "The product does not exist." }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" }, "403": { "description": "Forbidden" } }, "security": [ { "oauth2": [ ] } ] }, "get": { "tags": [ "Products" ], "summary": "Get Product", "description": "Retrieves detailed information about a specific product based on its unique SKU code. With this endpoint, you can access all pertinent data related to the product, including its description, origin, value, weight, and so on, which is essential for inventory management, shipping logistics, and compliance with customs regulations.", "parameters": [ { "name": "skuCode", "in": "path", "description": "A unique Stock Keeping Unit (SKU) code assigned to the product by you. This code is essential for tracking inventory, helping users identify specific products easily.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns the details of a product.", "content": { "application/json": { "schema": { "required": [ "CurrencyCode", "Description", "SkuCode", "Value", "Weight" ], "type": "object", "properties": { "LastUpdatedDateUtc": { "type": "string", "description": "A timestamp in Coordinated Universal Time (UTC) indicating when the product details were last updated. This helps users understand the recency of the product information.", "format": "date-time", "example": "2022-02-06T16:13:24.010Z" }, "LastUpdatedBy": { "type": "string", "description": "The identifier of the user or system that last modified the product details, ensuring accountability and traceability for updates.", "nullable": true, "example": "User A" }, "SkuCode": { "maxLength": 30, "minLength": 1, "type": "string", "description": "A unique Stock Keeping Unit (SKU) code assigned to the product. This code is essential for tracking inventory, helping users identify specific products easily.", "example": "SKU123" }, "Description": { "maxLength": 255, "minLength": 1, "type": "string", "description": "A brief summary providing details about the product, outlining its features, uses, and any pertinent information that helps users understand the product.\r
\r
***Note**: If you use the data of the stored product in your create shipment requests, then this description will be used as the item description for customs purposes, detailing the specific item being shipped.*", "example": "White Men Large T-shirt" }, "Value": { "maximum": 9999999.99, "minimum": 0.01, "type": "number", "description": "The commercial value of the product. This field is important for inventory valuation and pricing strategies.", "format": "double", "example": 19.99 }, "Weight": { "maximum": 1000000, "minimum": 0.001, "minLength": 1, "type": "string", "description": "The weight of the individual product in the unit of measure specified in the **WeightUnitOfMeasure** field.", "example": "0.5" }, "HSCode": { "maxLength": 13, "minLength": 6, "type": "string", "description": "The Harmonized System (HS) code used by customs to determine potential duties and taxes for the product. This code can be 6, 8, or 13 alphanumeric characters, depending on specific services or destinations. Some countries may also use the HS codes of other character lengths, such as 10 characters.", "nullable": true, "example": "6109100010" }, "CountryOfOrigin": { "maxLength": 2, "minLength": 2, "type": "string", "description": "An abbreviation representing the country where the product was manufactured or produced, following the ISO 3166-1 alpha-2 standard, for example, \"GB\" for the United Kingdom. This information is important for customs declarations and compliance with import/export regulations.", "nullable": true, "example": "GB" }, "CurrencyCode": { "maxLength": 3, "minLength": 3, "type": "string", "description": "An abbreviation representing the 3 letter ISO currency code in which the product's **Value** is expressed (for example, \"GBP\" for British pounds, \"EUR\" for euros). This is essential for financial transactions and international trade.", "example": "GBP" }, "WeightUnitOfMeasure": { "enum": [ "KG", "Grams" ], "type": "string", "description": "The unit of measurement for the weight provided, such as the product's **Weight**, indicating whether the weight is specified in kilograms (KG) or grams (G), ensuring clarity for shipping calculations." }, "ManufactureProductId": { "maxLength": 50, "type": "string", "description": "A unique manufacturer identifier for the item being shipped, for example, proprietary manufacturer code, model number, or internal code. This field is used to reference the shipped item and supports carrier-specific requirements.", "nullable": true }, "StandardisedProductId": { "maxLength": 50, "type": "string", "description": "A globally recognised product identifier for the item being shipped, for example, GTIN, EAN, and UPC. This field is used for standardised item identification and supports carrier-specific requirements for customs and risk assessment.", "nullable": true }, "Hazmat": { "required": [ "Class" ], "type": "object", "properties": { "UNCode": { "maxLength": 4, "minLength": 4, "type": "string", "description": "The United Nations (UN) code assigned to the hazardous material, which denotes its classification for transport. This code is critical for safety and compliance during shipping.", "nullable": true, "example": "1002" }, "ProperShippingName": { "maxLength": 100, "type": "string", "description": "The official name designated for the hazardous material as required by regulations. This name is used to inform handlers of the nature of the hazard during transport.", "nullable": true, "example": "Compressed Air" }, "Class": { "maxLength": 3, "minLength": 1, "type": "string", "description": "The class number of the hazardous material as per UN regulations, indicating the potential risk associated with the product.", "example": "9" }, "Id8000Category": { "type": "string", "description": "A specific category designation used for certain hazardous materials classified under Class 9, providing additional regulatory requirements for handling and transport.\r
Available values are the following:\r
", "nullable": true, "example": "Nail Varnish" }, "Quantity": { "maximum": 5, "type": "number", "description": "The quantity of the hazardous material in the specified **UnitOfMeasure**. This information is vital for compliance with shipping regulations pertaining to hazardous materials.", "format": "double", "nullable": true, "example": 3.5 }, "UnitOfMeasure": { "enum": [ "NONE", "L", "KG" ], "type": "string", "description": "The unit of measurement for the quantity of hazardous material, for example, litres (for liquids) or kilograms (for solids). This provides clarity regarding the amount of hazardous goods present." }, "EmergencyActionCode": { "maxLength": 4, "minLength": 4, "type": "string", "description": "A code providing emergency response instructions for handling hazardous materials during transport.This code is critical for safety and risk management.", "nullable": true, "example": "E012" }, "HazchemNumber": { "maxLength": 3, "minLength": 3, "type": "string", "description": "A number that indicates the type of hazardous material and the precautions necessary for its transport. This helps in emergency situations through quick identification.", "nullable": true }, "SpecialistAdviceContactNumber": { "maxLength": 20, "type": "string", "description": "A contact number for expert advice regarding the handling and transport of hazardous materials. This information is crucial during emergencies or if unusual situations arise.\r
\r
***Note:** If this information is not provided and the hazardous material is used in your **Create Shipment** request, then the contact number will be sent from the customer shipping account record.*", "nullable": true } }, "description": "Specifies the details whether the product is classified as hazardous material. This designation impacts shipping regulations and handling procedures." } }, "description": "Product List" } } } }, "404": { "description": "The product does not exist." }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" }, "403": { "description": "Forbidden" } }, "security": [ { "oauth2": [ ] } ] }, "put": { "tags": [ "Products" ], "summary": "Update Product", "description": "Modify the details of an existing product in the system based on its unique SKU code. With this endpoint, you can submit updates for various product attributes, ensuring that the product information remains current and accurate. This functionality is essential for inventory management, compliance with shipping regulations, and maintaining accurate records.", "parameters": [ { "name": "skuCode", "in": "path", "description": "A unique Stock Keeping Unit (SKU) code assigned to the product by you. This code is essential for tracking inventory, helping users identify specific products easily.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Product details", "content": { "application/json": { "schema": { "required": [ "CurrencyCode", "Description", "SkuCode", "Value", "Weight" ], "type": "object", "properties": { "SkuCode": { "maxLength": 30, "minLength": 1, "type": "string", "description": "A unique Stock Keeping Unit (SKU) code assigned to the product. This code is essential for tracking inventory, helping users identify specific products easily.", "example": "SKU123" }, "Description": { "maxLength": 255, "minLength": 1, "type": "string", "description": "A brief summary providing details about the product, outlining its features, uses, and any pertinent information that helps users understand the product.\r
\r
***Note**: If you use the data of the stored product in your create shipment requests, then this description will be used as the item description for customs purposes, detailing the specific item being shipped.*", "example": "White Men Large T-shirt" }, "Value": { "maximum": 9999999.99, "minimum": 0.01, "type": "number", "description": "The commercial value of the product. This field is important for inventory valuation and pricing strategies.", "format": "double", "example": 19.99 }, "Weight": { "maximum": 1000000, "minimum": 0.001, "minLength": 1, "type": "string", "description": "The weight of the individual product in the unit of measure specified in the **WeightUnitOfMeasure** field.

***Note**: The maximum allowed weight is 1000 grams. For dutiable shipments, the minimum allowed weight is 0.001 Kg.*", "example": "0.5" }, "HSCode": { "maxLength": 13, "minLength": 6, "type": "string", "description": "The Harmonized System (HS) code used by customs to determine potential duties and taxes for the product. This code can be 6, 8, or 13 alphanumeric characters, depending on specific services or destinations. Some countries may also use the HS codes of other character lengths, such as 10 characters.

***Note**: Characters like space and dot are supported.*", "nullable": true, "example": "6109100010" }, "CountryOfOrigin": { "maxLength": 2, "minLength": 2, "type": "string", "description": "An abbreviation representing the country where the product was manufactured or produced, following the ISO 3166-1 alpha-2 standard, for example, \"GB\" for the United Kingdom. This information is important for customs declarations and compliance with import/export regulations.", "nullable": true, "example": "GB" }, "CurrencyCode": { "maxLength": 3, "minLength": 3, "type": "string", "description": "An abbreviation representing the 3 letter ISO currency code in which the product's **Value** is expressed (for example, \"GBP\" for British pounds, \"EUR\" for euros). This is essential for financial transactions and international trade.", "example": "GBP" }, "WeightUnitOfMeasure": { "enum": [ "KG", "Grams" ], "type": "string", "description": "The unit of measurement for the weight provided, such as the product's **Weight**, indicating whether the weight is specified in kilograms (KG) or grams (G), ensuring clarity for shipping calculations.

***Note**: By default, this field is set to KG.*

" }, "ManufactureProductId": { "maxLength": 50, "type": "string", "description": "A unique manufacturer identifier for the item being shipped, for example, proprietary manufacturer code, model number, or internal code.

This field is used to reference the shipped item and supports carrier-specific requirements.", "nullable": true }, "StandardisedProductId": { "maxLength": 50, "type": "string", "description": "A globally recognised product identifier for the item being shipped, for example, GTIN, EAN, and UPC.

This field is used for standardised item identification and supports carrier-specific requirements for customs and risk assessment.", "nullable": true }, "Hazmat": { "required": [ "Class" ], "type": "object", "properties": { "UNCode": { "maxLength": 4, "minLength": 4, "type": "string", "description": "The United Nations (UN) code assigned to the hazardous material, which denotes its classification for transport. This code is critical for safety and compliance during shipping.

***Note**: This field must be populated only for domestic shipments using class 9 dangerous goods.If provided, then **Quantity** and **UnitOfMeasure** must also be specified.*", "nullable": true, "example": "1002" }, "ProperShippingName": { "maxLength": 100, "type": "string", "description": "The official name designated for the hazardous material as required by regulations. This name is used to inform handlers of the nature of the hazard during transport.", "nullable": true, "example": "Compressed Air" }, "Class": { "maxLength": 3, "minLength": 1, "type": "string", "description": "The class number of the hazardous material as per UN regulations, indicating the potential risk associated with the product.", "example": "9" }, "Id8000Category": { "type": "string", "description": "A specific category designation used for certain hazardous materials classified under Class 9, providing additional regulatory requirements for handling and transport.\r
Available values are the following:\r
", "nullable": true, "example": "Nail Varnish" }, "Quantity": { "maximum": 5, "type": "number", "description": "The quantity of the hazardous material in the specified **UnitOfMeasure**. This information is vital for compliance with shipping regulations pertaining to hazardous materials.

***Note**: This field is only required if **UnitOfMeasure** and **UNCode** is specified.*", "format": "double", "nullable": true, "example": 3.5 }, "UnitOfMeasure": { "enum": [ "NONE", "L", "KG" ], "type": "string", "description": "The unit of measurement for the quantity of hazardous material, for example, litres (for liquids) or kilograms (for solids). This provides clarity regarding the amount of hazardous goods present.

***Note**: This field is only required if **Quantity** and **UNCode** is specified.*

" }, "EmergencyActionCode": { "maxLength": 4, "minLength": 4, "type": "string", "description": "A code providing emergency response instructions for handling hazardous materials during transport.This code is critical for safety and risk management.", "nullable": true, "example": "E012" }, "HazchemNumber": { "maxLength": 3, "minLength": 3, "type": "string", "description": "A number that indicates the type of hazardous material and the precautions necessary for its transport. This helps in emergency situations through quick identification.", "nullable": true }, "SpecialistAdviceContactNumber": { "maxLength": 20, "type": "string", "description": "A contact number for expert advice regarding the handling and transport of hazardous materials. This information is crucial during emergencies or if unusual situations arise.\r
\r
***Note:** If this information is not provided and the hazardous material is used in your **Create Shipment** request, then the contact number will be sent from the customer shipping account record.*", "nullable": true } }, "description": "Specifies the details whether the product is classified as hazardous material. This designation impacts shipping regulations and handling procedures." } }, "description": "Product" }, "examples": { "Update": { "value": { "SkuCode": "SKU123", "Description": "White Men Large T-shirt", "Value": 19.99, "Weight": "0.5", "HSCode": "6109100010", "CountryOfOrigin": "GB", "CurrencyCode": "GBP", "WeightUnitOfMeasure": "KG", "ManufactureProductId": "5449000000996", "StandardisedProductId": "4006381333931", "Hazmat": { "UNCode": "1002", "ProperShippingName": "Compressed Air", "Class": "9", "Id8000Category": "Nail Varnish", "Quantity": "3.5", "UnitOfMeasure": "L", "EmergencyActionCode": "E012", "HazchemNumber": "string", "SpecialistAdviceContactNumber": "string" } } } } } } }, "responses": { "200": { "description": "The product was updated successfully." }, "400": { "description": "Invalid request response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "Message": "Invalid Request", "Errors": [ { "Message": "The product SKU code maximum length is 30 characters.", "Cause": "skuCode", "ErrorCode": "E1002" } ] } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" }, "403": { "description": "Forbidden" } }, "security": [ { "oauth2": [ ] } ] } }, "/v4/countries": { "get": { "tags": [ "Reference Data" ], "summary": "Get Countries", "description": "Retrieves a list of countries available on the system along with their relevant details. \r
With this endpoint, you can search for specific countries, paginate results, and sort the data as needed.", "parameters": [ { "name": "searchTerm", "in": "query", "description": "A string representing the term or keywords used to filter the list of countries, \r
helping users to narrow down the list based on the their input.", "schema": { "type": "string" } }, { "name": "pageSize", "in": "query", "description": "An integer that defines the maximum number of countries (records) returned per page in the response. \r
For instance, if pageSize is set to 20, the API will return up to 20 countries in each response.\r
\r
*Note: By default, this value is set to 100.*", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "default": 100 } }, { "name": "pageNumber", "in": "query", "description": "An integer indicating the specific page of results to retrieve, allowing for pagination of larger datasets. \r
For example, if pageNumber is set to 3, the API will return the results corresponding to the third page of countries based on the specified pageSize.\r
\r
*Note: By default, this value is set to 1.*", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "default": 1 } }, { "name": "sortBy", "in": "query", "description": "A string specifying the field by which to organise the search results. \r
For instance, \"CountryName\" could be used to sort countries alphabetically, arranging the results in a more user-friendly order.\r
\r
*Note: By default, this value is set to CountryName.*\r
\r
Enum [CountryName, Alpha2Code, Alpha3Code, Numeric, CountryGroup, PostCodeRequired, StateCodeRequired, DefaultCurrency]", "schema": { "$ref": "#/components/schemas/CountriesSortBy" } }, { "name": "sortDir", "in": "query", "description": "A string indicating the direction in which to sort the results, typically set to \"ascending\" or \"descending.\" \r
For example, setting sortDir to \"Ascending\" while using \"CountryName\" as sortBy would arrange the countries from A to Z.\r
\r
*Note: By default, this value is set to Ascending.*\r
\r
Enum [Ascending, Descending]", "schema": { "$ref": "#/components/schemas/OrderDirection" } } ], "responses": { "200": { "description": "Returns a list of countries.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountriesPagedResponse" } } } }, "400": { "description": "Invalid request response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "Message": "Invalid Request", "Errors": [ { "Message": "The page size must be 1 or greater.", "Cause": "pageSize", "ErrorCode": "E1002" }, { "Message": "The page number must be 1 or greater.", "Cause": "pageNumber", "ErrorCode": "E1002" } ] } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" }, "403": { "description": "Forbidden" } }, "security": [ { "oauth2": [ ] } ] } }, "/v4/currencies": { "get": { "tags": [ "Reference Data" ], "summary": "Get Currencies", "description": "Retrieves a list of currencies available on the system along with their relevant details.\r
With this endpoint, you can search for specific currencies, paginate results, and sort the data as needed.", "parameters": [ { "name": "searchTerm", "in": "query", "description": "A string representing the term or keywords used to filter the list of currencies, \r
helping users to narrow down the list based on the their input.", "schema": { "type": "string" } }, { "name": "pageSize", "in": "query", "description": "An integer that defines the maximum number of currencies (records) returned per page in the response. \r
For instance, if pageSize is set to 20, the API will return up to 20 currencies in each response.\r
\r
Note: By default, this value is set to 100.", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "default": 100 } }, { "name": "pageNumber", "in": "query", "description": "An integer indicating the specific page of results to retrieve, allowing for pagination of larger datasets. \r
For example, if pageNumber is set to 3, the API will return the results corresponding to the third page of locations based on the specified pageSize.\r
\r
Note: By default, this value is set to 1.", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "default": 1 } }, { "name": "sortBy", "in": "query", "description": "A string specifying the field by which to organise the search results. \r
For instance, \"CurrencyName\" could be used to sort currencies alphabetically, arranging the results in a more user-friendly order.\r
\r
Note: By default, this value is set to CurrencyName.\r
\r
Enum [CurrencyName, CurrencyCode]", "schema": { "$ref": "#/components/schemas/CurrenciesSortBy" } }, { "name": "sortDir", "in": "query", "description": "A string indicating the direction in which to sort the results, typically set to \"ascending\" or \"descending.\" \r
For example, setting sortDir to \"Ascending\" while using \"CurrencyName\" as sortBy would arrange the currencies from A to Z.\r
\r
Note: By default, this value is set to Ascending.\r
\r
Enum [Ascending, Descending]", "schema": { "$ref": "#/components/schemas/OrderDirection" } } ], "responses": { "200": { "description": "Returns a list of currencies.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrenciesPagedResponse" } } } }, "400": { "description": "Invalid request response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "Message": "Invalid Request", "Errors": [ { "Message": "The page size must be 1 or greater.", "Cause": "pageSize", "ErrorCode": "E1002" }, { "Message": "The page number must be 1 or greater.", "Cause": "pageNumber", "ErrorCode": "E1002" } ] } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" }, "403": { "description": "Forbidden" } }, "security": [ { "oauth2": [ ] } ] } }, "/v4/timezones": { "get": { "tags": [ "Reference Data" ], "summary": "Get Time Zones", "description": "Retrieves a list of time zones available on the system along with their relevant details. \r
With this endpoint, you can search for specific time zones, paginate results, and sort the data as needed.", "parameters": [ { "name": "countryCode", "in": "query", "description": "A two-letter ISO 3166-1 alpha-2 code that represents a specific country. \r
This parameter is used to filter the list of time zones returned by the API, allowing users to retrieve only the time zones that are associated with the specified country.", "schema": { "type": "string", "default": "" } }, { "name": "searchTerm", "in": "query", "description": "A string representing the term or keywords used to filter the list of time zones, helping users to narrow down the list based on their input.", "schema": { "type": "string", "default": "" } }, { "name": "pageSize", "in": "query", "description": "An integer that defines the maximum number of time zone records returned per page in the response. \r
For instance, if pageSize is set to 20, the API will return up to 20 time zones in each response.\r
\r
Note: By default, this value is set to 100.", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "default": 100 } }, { "name": "pageNumber", "in": "query", "description": "An integer indicating the specific page of results to retrieve, allowing for pagination of larger datasets. \r
For example, if pageNumber is set to 3, the API will return the results corresponding to the third page of locations based on the specified pageSize.\r
\r
Note: By default, this value is set to 1.", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "default": 1 } }, { "name": "sortBy", "in": "query", "description": "A string specifying the field by which to organise the search results. \r
For instance, \"TimeZoneName\" could be used to sort countries alphabetically, arranging the results in a more user-friendly order.\r
\r
Note: By default, this value is set to CountryCode.\r
\r
Enum [TimeZoneName, Country, CountryCode]", "schema": { "$ref": "#/components/schemas/TimezonesSortBy" } }, { "name": "sortDir", "in": "query", "description": "A string indicating the direction in which to sort the results, typically set to \"ascending\" or \"descending\".\r
For example, setting sortDir to \"Ascending\" while using \"CountryName\" as sortBy would arrange the countries from A to Z.\r
\r
Note: By default, this value is set to Ascending.\r
\r
Enum [Ascending, Descending]", "schema": { "$ref": "#/components/schemas/OrderDirection" } } ], "responses": { "200": { "description": "Returns a list of all the time zones for a given country.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimezonesPagedResponse" } } } }, "400": { "description": "Invalid request response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "Message": "Invalid Request", "Errors": [ { "Message": "The page size must be 1 or greater.", "Cause": "pageSize", "ErrorCode": "E1002" }, { "Message": "The page number must be 1 or greater.", "Cause": "pageNumber", "ErrorCode": "E1002" } ] } } } }, "404": { "description": "The country code does not exist." }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" }, "403": { "description": "Forbidden" } }, "security": [ { "oauth2": [ ] } ] } }, "/v4/shippingLocations": { "get": { "tags": [ "Shipping Locations" ], "summary": "Get Locations", "description": "Retrieves a list of all shipping locations set up on the system under your customer account.", "parameters": [ { "name": "searchTerm", "in": "query", "description": "A string representing the term or keywords used to filter location results. For example, a search term like \"Manchester\" would return locations associated with that city, helping to narrow down the list based on the user input.", "schema": { "type": "string" } }, { "name": "pageSize", "in": "query", "description": "An integer that defines the number of location entries (record) returned per page in the response. For instance, if **pageSize** is set to 20, the API will return up to 20 locations in each response.\r
\r
***Note:** By default, this value is set to 100.*", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "default": 100 } }, { "name": "pageNumber", "in": "query", "description": "An integer indicating the specific page of results to retrieve, allowing for pagination of larger datasets. For example, if **pageNumber** is set to 3, the API will return the results corresponding to the third page of locations based on the specified **pageSize**.\r
\r
***Note:** By default, this value is set to 1.*", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "default": 1 } }, { "name": "sortBy", "in": "query", "description": "A string specifying the field by which to organise the search results. For instance, \"Name\" could be used to sort locations alphabetically, arranging the results in a more user-friendly order.\r
\r
***Note:** By default, this value is set to Name.*", "schema": { "$ref": "#/components/schemas/ShippingLocationsSortBy" } }, { "name": "sortDir", "in": "query", "description": "A string indicating the direction in which to sort the results, typically set to \"ascending\" or \"descending.\" For example, setting **sortDir** to \"Ascending\" while using \"Name\" as **sortBy** would arrange the locations from A to Z.\r
\r
***Note:** By default, this value is set to Ascending.*\r
\r
Enum [ Ascending, Descending]", "schema": { "$ref": "#/components/schemas/OrderDirection" } } ], "responses": { "200": { "description": "Returns a paged list of shipping locations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShippingLocationsPagedResponse" } } } }, "400": { "description": "Invalid request response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "Message": "Invalid Request", "Errors": [ { "Message": "The page size must be 1 or greater.", "Cause": "pageSize", "ErrorCode": "E1002" }, { "Message": "The page number must be 1 or greater.", "Cause": "pageNumber", "ErrorCode": "E1002" } ] } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" }, "403": { "description": "Forbidden" } }, "security": [ { "oauth2": [ ] } ] }, "post": { "tags": [ "Shipping Locations" ], "summary": "Add Location", "description": "Create a new shipping location in the system by providing the location alias, timezone, and address details.", "requestBody": { "description": "Shipping Location Details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddShippingLocationRequest" }, "examples": { "Add Shipping Location": { "value": { "LocationAlias": "Main Warehouse", "Timezone": "Europe/London", "IsDefaultLocation": false, "Address": { "ContactPhone": "07123887422", "Line1": "Brown Cottage", "Line2": "10 Sky Lane", "Line3": "Hills End", "Town": "Christchurch", "Postcode": "TW20 0HJ", "County": "Surrey", "CountryCode": "GB", "What3Words": "brick.space.employ" } } }, "Using Address Book": { "value": { "LocationAlias": "Main Warehouse", "Timezone": "Europe/London", "IsDefaultLocation": false, "Address": { "AddressId": "John Brown Default" } } } } } } }, "responses": { "200": { "description": "The shipping location was created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddShippingLocationResponse" }, "examples": { "Add Shipping Location": { "value": { "LocationAlias": "Main Warehouse", "Timezone": "Europe/London", "IsDefaultLocation": false, "Address": { "ContactPhone": "07123887422", "Line1": "Brown Cottage", "Line2": "10 Sky Lane", "Line3": "Hills End", "Town": "Christchurch", "Postcode": "TW20 0HJ", "County": "Surrey", "CountryCode": "GB", "What3Words": "brick.space.employ" } } }, "Using Address Book": { "value": { "LocationAlias": "Main Warehouse", "Timezone": "Europe/London", "IsDefaultLocation": false, "Address": { "AddressId": "John Brown Default" } } } } } } }, "400": { "description": "Invalid request response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "Message": "Invalid Request", "Errors": [ { "Message": "The location alias is required.", "Cause": "LocationAlias", "ErrorCode": "E1001" } ] } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" }, "403": { "description": "Forbidden" } }, "security": [ { "oauth2": [ ] } ] } }, "/v4/shippingLocations/{shippingLocationId}": { "get": { "tags": [ "Shipping Locations" ], "summary": "Get Location", "description": "Retrieves information on a specific shipping location set up on the system under your customer account. The information typically includes location, timezone, address, and so on.", "parameters": [ { "name": "shippingLocationId", "in": "path", "description": "A unique identifier assigned to the shipping location by the system (ShippingLocationId) or by you (alias). This ID is used to distinguish between different shipping locations within the system, facilitating, referencing and operations, such as updates, deletions, or specific queries related to that location.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns the shipping location.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShippingLocation" } } } }, "404": { "description": "The shipping location was not found." }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" }, "403": { "description": "Forbidden" } }, "security": [ { "oauth2": [ ] } ] }, "put": { "tags": [ "Shipping Locations" ], "summary": "Update Location", "description": "Modify the details of an existing shipping location, such as address, contact details, and any other relevant fields.\r
\r
***Note:** All the required fields must be populated in the request, regardless of whether they need to be updated.*", "parameters": [ { "name": "shippingLocationId", "in": "path", "description": "A unique identifier assigned to the shipping location by the system (shippingLocationId) or by you (LocationAlias). This ID is used to distinguish between different shipping locations within the system, facilitating, referencing and operations, such as updates, deletions, or specific queries related to that location.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Shipping Location Details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShippingLocationRequest" } } } }, "responses": { "200": { "description": "The shipping location was updated successfully." }, "404": { "description": "The shipping location was not found." }, "400": { "description": "Invalid request response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "Message": "Invalid Request", "Errors": [ { "Message": "The location alias is required.", "Cause": "LocationAlias", "ErrorCode": "E1001" } ] } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" }, "403": { "description": "Forbidden" } }, "security": [ { "oauth2": [ ] } ] }, "delete": { "tags": [ "Shipping Locations" ], "summary": "Delete Location", "description": "Delete an existing shipping location that is no longer required from the system.", "parameters": [ { "name": "shippingLocationId", "in": "path", "description": "A unique identifier assigned to the shipping location by the system (shippingLocationId) or by you (LocationAlias). This ID is used to distinguish between different shipping locations within the system, facilitating, referencing and operations, such as updates, deletions, or specific queries related to that location.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The shipping location was deleted successfully." }, "400": { "description": "Invalid request response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "Message": "Invalid Request", "Errors": [ { "Message": "The shipping location is associated with shipping accounts and cannot be deleted.", "Cause": "ShippingLocationId", "ErrorCode": "E1002" }, { "Message": "The shipping location is associated with users and cannot be deleted.", "Cause": "ShippingLocationId", "ErrorCode": "E1002" }, { "Message": "The shipping location is set as the default shipping location for a customer and cannot be deleted.", "Cause": "ShippingLocationId", "ErrorCode": "E1002" } ] } } } }, "404": { "description": "The shipping location was not found." }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" }, "403": { "description": "Forbidden" } }, "security": [ { "oauth2": [ ] } ] } }, "/v4/shippingLocations/{shippingLocationId}/shippingAccounts": { "get": { "tags": [ "Shipping Locations" ], "summary": "Get Associated Accounts", "description": "Retrieves a list of shipping accounts that are linked to a specific shipping location.", "parameters": [ { "name": "shippingLocationId", "in": "path", "description": "A unique identifier assigned to the shipping location by the system (**shippingLocationId**) or by you (**LocationAlias**). This ID is used to distinguish between different shipping locations within the system, facilitating referencing and operations, such as updates, deletions, or specific queries related to that location.", "required": true, "schema": { "type": "string" } }, { "name": "searchTerm", "in": "query", "description": "A string representing the term or keywords used to filter location results. For example, a search term like \"Manchester\" would return locations associated with that city, helping to narrow down the list based on the user input.", "schema": { "type": "string" } }, { "name": "pageSize", "in": "query", "description": "An integer that defines the number of location entries (record) returned per page in the response. For instance, if **pageSize** is set to 20, the API will return up to 20 locations in each response.\r
\r
***Note**: By default, this value is set to 100.*", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "default": 100 } }, { "name": "pageNumber", "in": "query", "description": "An integer indicating the specific page of results to retrieve, allowing for pagination of larger datasets. For example, if **pageNumber** is set to 3, the API will return the results corresponding to the third page of locations based on the specified **pageSize**.\r
\r
***Note**: By default, this value is set to 1.*", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "default": 1 } }, { "name": "sortBy", "in": "query", "description": "A string specifying the field by which to organise the search results. For instance, \"Name\" could be used to sort locations alphabetically, arranging the results in a more user-friendly order.\r
\r
***Note**: By default, this value is set to Name.*", "schema": { "$ref": "#/components/schemas/ShippingAccountsSortBy" } }, { "name": "sortDir", "in": "query", "description": "A string indicating the direction in which to sort the results, typically set to \"ascending\" or \"descending.\" For example, setting **sortDir** to \"Ascending\" while using \"Name\" as **sortBy** would arrange the locations from A to Z.\r
\r
***Note**: By default, this value is set to Ascending.*", "schema": { "$ref": "#/components/schemas/OrderDirection" } } ], "responses": { "200": { "description": "Returns a paged list of associated shipping accounts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShippingAccountsPagedResponse" } } } }, "404": { "description": "The shipping location was not found." }, "400": { "description": "Invalid request response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "Message": "Invalid Request", "Errors": [ { "Message": "The page size must be 1 or greater.", "Cause": "pageSize", "ErrorCode": "E1002" }, { "Message": "The page number must be 1 or greater.", "Cause": "pageNumber", "ErrorCode": "E1002" } ] } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" }, "403": { "description": "Forbidden" } }, "security": [ { "oauth2": [ ] } ] } }, "/v4/shippingLocations/{carrierCode}": { "get": { "tags": [ "Shipping Locations" ], "summary": "Get Carrier Locations", "description": "Retrieves a list of all shipping locations associated with a specific carrier. \r
\r
***Note**: A shipping location can be associated with more than one carrier. However, to get the carrier locations, you need to make individual API requests for each carrier.*", "parameters": [ { "name": "carrierCode", "in": "path", "description": "A unique identifier for the carrier associated with the shipping location. This code is alphanumeric and helps in identifying the specific carrier linked to the shipping location.", "required": true, "schema": { "type": "string" } }, { "name": "searchTerm", "in": "query", "description": "A string representing the term or keywords used to filter location results. For example, a search term like \"Manchester\" would return locations associated with that city, helping to narrow down the list based on the user input.", "schema": { "type": "string" } }, { "name": "pageSize", "in": "query", "description": "An integer that defines the number of location entries (record) returned per page in the response. For instance, if **pageSize** is set to 20, the API will return up to 20 locations in each response.\r
\r
***Note**: By default, this value is set to 100.*", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "default": 100 } }, { "name": "pageNumber", "in": "query", "description": "An integer indicating the specific page of results to retrieve, allowing for pagination of larger datasets. For example, if **pageNumber** is set to 3, the API will return the results corresponding to the third page of locations based on the specified **pageSize**.\r
\r
***Note**: By default, this value is set to 1.*", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "default": 1 } }, { "name": "sortBy", "in": "query", "description": "A string specifying the field by which to organise the search results. For instance, \"Name\" could be used to sort locations alphabetically, arranging the results in a more user-friendly order.\r
\r
***Note**: By default, this value is set to Name.*", "schema": { "$ref": "#/components/schemas/ShippingLocationsSortBy" } }, { "name": "sortDir", "in": "query", "description": "A string indicating the direction in which to sort the results, typically set to \"ascending\" or \"descending.\" For example, setting **sortDir** to \"Ascending\" while using \"Name\" as **sortBy** would arrange the locations from A to Z.\r
\r
***Note**: By default, this value is set to Ascending.*", "schema": { "$ref": "#/components/schemas/OrderDirection" } } ], "responses": { "200": { "description": "Returns a paged list of shipping locations linked to accounts for the given carrier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShippingLocationsPagedResponse" } } } }, "400": { "description": "Invalid request response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "Message": "Invalid Request", "Errors": [ { "Message": "The page size must be 1 or greater.", "Cause": "pageSize", "ErrorCode": "E1002" }, { "Message": "The page number must be 1 or greater.", "Cause": "pageNumber", "ErrorCode": "E1002" } ] } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" }, "403": { "description": "Forbidden" } }, "security": [ { "oauth2": [ ] } ] } } }, "components": { "schemas": { "AccountType": { "enum": [ "Sandbox", "Production" ], "type": "string", "description": "Indicates whether the account is set up as a \"sandbox\" or \"production\" account. A **Sandbox** account is for testing and development, while a **Production** account is used for live shipments and transactions." }, "AddAddressBook": { "required": [ "CountryCode", "Line1", "Town" ], "type": "object", "properties": { "AddressId": { "maxLength": 70, "type": "string", "description": "A unique identifier for each address record. This information ensures that each address can be distinctly referenced and managed within the system.", "nullable": true, "example": "John Brown Default" }, "ContactName": { "maxLength": 50, "type": "string", "description": "The name of the primary contact associated with the address. This field is essential for identification and communication purposes.", "nullable": true, "example": "Jane Doe" }, "CompanyName": { "maxLength": 50, "type": "string", "description": "The name of the company linked to the address. This field provides context for the address, especially in business-related queries.", "nullable": true, "example": "My Company Ltd." }, "ContactEmail": { "maxLength": 254, "type": "string", "description": "The email address of the primary contact for the address. This is used for correspondence and can facilitate communication directly related to the address.", "format": "email", "nullable": true, "example": "jane@example.com" }, "ContactPhone": { "maxLength": 20, "type": "string", "description": "The phone number of the primary contact associated with the address. This field is crucial for any immediate communication needs.", "format": "tel", "nullable": true }, "Line1": { "maxLength": 50, "minLength": 1, "type": "string", "description": "The first line of the address, typically containing the primary address information such as house number and street name.", "example": "10 Sky Lane" }, "Line2": { "maxLength": 50, "type": "string", "description": "An optional second line for the address, often used for additional details like apartment numbers or suite designations.", "nullable": true }, "Line3": { "maxLength": 50, "type": "string", "description": "A third optional line in the address to include any further address specifications, allowing for more detailed address information if necessary.", "nullable": true }, "Town": { "maxLength": 50, "minLength": 1, "type": "string", "description": "The town or city, indicating the specific locality where the address is located." }, "Postcode": { "maxLength": 20, "type": "string", "description": "The postal or ZIP code corresponding to the address, used to identify specific geographic areas.", "nullable": true }, "County": { "maxLength": 50, "type": "string", "description": "The county, state, or province in which the address is located, providing additional geographical context for the address.", "nullable": true }, "CountryCode": { "maxLength": 2, "minLength": 2, "type": "string", "description": "An abbreviation representing the country of the address, following the ISO 3166-1 alpha-2 standard, for example, \"GB\" for the United Kingdom.", "example": "GB" }, "What3Words": { "type": "string", "description": "A three-word location identifier provided by the What3words service, offering a precise way to define addresses using a unique combination of three words, for example, the front door of 10 Downing Street in London is identified by slurs.this.shark.", "nullable": true, "example": "brick.space.employ" } }, "additionalProperties": false, "description": "Add Address Book" }, "AddAddressBookResponse": { "type": "object", "properties": { "AddressId": { "type": "string", "description": "A unique identifier for each address record assigned by the system. This information ensures that each address is distinctly referenced and managed within the system.", "nullable": true, "example": "93f6d928-9456-434a-9d69-60f3b7dea091" } }, "additionalProperties": false, "description": "Add Address Book Response" }, "AddContainerRequest": { "required": [ "CarrierCode", "ShippingLocationId" ], "type": "object", "properties": { "CarrierCode": { "maxLength": 10, "minLength": 1, "type": "string", "description": "A unique identifier for the shipping carrier for which a container is being created. This code is alphanumeric and helps in identifying the specific carrier linked to the container.", "example": "RM" }, "ShippingLocationId": { "maxLength": 100, "minLength": 1, "type": "string", "description": "A unique identifier for the shipping location assigned by the system (**ShippingLocationId**) or by you (**LocationAlias**) where the container will be stored or from which it will be dispatched. This parameter links the new container to a specific physical location, aiding in inventory management and logistical operations.", "example": "Central Warehouse" }, "ContainerId": { "maxLength": 50, "type": "string", "description": "A unique identifier for the new container being created. This ID is used to reference and manage the specific container within the PRO SHIPPING system, facilitating tracking and operational oversight.\r
\r
***Note**: If this information is not provided, then by default, this field is set to the globally unique identifier (GUID).*", "nullable": true, "example": "South East 1234" } }, "additionalProperties": false, "description": "Add Container Request" }, "AddContainerResponse": { "required": [ "CarrierCode", "ContainerId", "CreatedDate", "CreatedDateUtc", "ShippingLocationId" ], "type": "object", "properties": { "ContainerId": { "minLength": 1, "type": "string", "description": "The unique identifier assigned to the newly created container. This ID is returned to the user as confirmation that the container has been successfully added to the system.", "example": "South East 1234" }, "CreatedDateUtc": { "type": "string", "description": "A timestamp indicating when the container was created in the system, formatted in Coordinated Universal Time (UTC). This information helps users to track the age and relevance of their container records.", "format": "date-time" }, "CreatedDate": { "type": "string", "description": "The specific date on which the container was created. This provides a clear reference for users to understand when the container was added to the system.", "format": "date-time" }, "CarrierCode": { "minLength": 1, "type": "string", "description": "A unique identifier for the shipping carrier associated with the new container. This code is alphanumeric and helps confirming which carrier will handle the shipping and logistics for that container.", "example": "RM" }, "ShippingLocationId": { "minLength": 1, "type": "string", "description": "The unique identifier assigned by the user (alias) to the shipping location linked to the newly added container, providing context about where the container is stored or from where it will be despatched.", "example": "Northern Warehouse" } }, "additionalProperties": false, "description": "Container" }, "AddProductResponse": { "required": [ "SkuCode" ], "type": "object", "properties": { "SkuCode": { "maxLength": 30, "minLength": 1, "type": "string", "description": "A unique Stock Keeping Unit (SKU) code assigned to the product. This code is essential for tracking inventory, helping users identify specific products easily.", "example": "SKU123" } }, "additionalProperties": false, "description": "AddProduct Response" }, "AddShippingLocationAddress": { "type": "object", "properties": { "AddressId": { "maxLength": 70, "type": "string", "description": "A unique identifier for the address associated with the shipping location. This ID serves as a reference point, allowing users to easily access, manage, and differentiate between different addresses stored in the system.\r
\r
***Note:** This ID is stored in the system's address book. If this information is provided, then all the fields under the **Address** object are ignored and the stored address in the **Address Book** will be used.*", "nullable": true, "example": "John Brown Default" }, "Line1": { "maxLength": 50, "type": "string", "description": "The first line of the address, typically containing the primary address information such as house number and street name. \r
A maximum of 50 characters is permitted. However, it may vary depending on the carrier selection.\r
\r
***Note:** This information is only required if the address is not used from the stored addresses in the **Address Book**.*", "nullable": true, "example": "Brown Cottage" }, "Line2": { "maxLength": 50, "type": "string", "description": "An optional second line for the address, often used for additional details like apartment numbers or suite designations.\r
A maximum of 50 characters is permitted. However, it may vary depending on the carrier selection.", "nullable": true, "example": "10 Sky Lane" }, "Line3": { "maxLength": 50, "type": "string", "description": "A third optional line in the address to include any further address specifications, allowing for more detailed address information if necessary.\r
A maximum of 50 characters is permitted. However, it may vary depending on the carrier selection.", "nullable": true, "example": "Hills End" }, "Town": { "maxLength": 50, "type": "string", "description": "The town or city, indicating the specific locality where the shipping location is situated.\r
A maximum of 50 characters is permitted. However, it may vary depending on the carrier selection.\r
\r
***Note:** This information is only required if the address is not used from the stored addresses in the Address Book.*", "nullable": true, "example": "Christchurch" }, "Postcode": { "maxLength": 20, "type": "string", "description": "The postal or ZIP code corresponding to the shipping location, used for mail sorting and to identify specific geographic areas.\r
A maximum of 50 characters is permitted. However, it may vary depending on the carrier selection. \r
\r
***Note:** This information is only required for the addresses in the UK and for some outside it. To check for the postcode requirements, refer to the **Countries** API.*", "nullable": true, "example": "TW20 0HJ" }, "County": { "maxLength": 50, "type": "string", "description": "The county, state, or province in which the shipping location resides, providing additional geographical context for the address.\r
A maximum of 50 characters is permitted. However, it may vary depending on the carrier selection.\r
\r
***Note:** This information may be required depending on the country. If the country is USA, Australia, or Canada, then it must be a valid state code or name. To check for the county/state/province requirements, refer to the **Countries** API.*", "nullable": true, "example": "Surrey" }, "CountryCode": { "maxLength": 2, "minLength": 2, "type": "string", "description": "An abbreviation representing the country of the shipping location, following the ISO 3166-1 alpha-2 standard, for example, \"GB\" for the United Kingdom.\r
\r
***Note**: This information is only required if the address is not used from the stored addresses in the **Address Book***", "nullable": true, "example": "GB" }, "What3Words": { "type": "string", "description": "A three-word location identifier provided by the What3words service, offering a precise way to define locations using a unique combination of three words, for example, the front door of 10 Downing Street in London is identified by slurs.this.shark.", "nullable": true, "example": "brick.space.employ" }, "ContactPhone": { "maxLength": 20, "type": "string", "description": "The contact phone number associated with the shipping location, facilitating communication regarding shipments or deliveries.\r
\r
***Note:** Characters like +, /, -, or space are supported.*", "format": "tel", "nullable": true, "example": "07123887422" } }, "additionalProperties": false, "description": "The complete address of the shipping location, consisting of multiple components including street information, locality, and so on." }, "AddShippingLocationRequest": { "required": [ "Address", "LocationAlias", "Timezone" ], "type": "object", "properties": { "LocationAlias": { "maxLength": 100, "minLength": 1, "type": "string", "description": "A user-defined identifier for the shipping location. This information allows greater flexibility in recognising and referring to the location.", "example": "Main Warehouse" }, "Timezone": { "maxLength": 100, "minLength": 1, "type": "string", "description": "The timezone in which the shipping location is located, important for scheduling and logistical considerations.", "example": "Europe/London" }, "IsDefaultLocation": { "type": "boolean", "description": "A boolean value indicating whether the shipping location is set as the default for shipping operations, streamlining the selection process during shipments.\r
\r
If the location is set as the default one, the customers no longer need to specify the location for every shipment request, reducing the risk of errors and delays. It enhances consistency by ensuring that all shipments are directed to the same default location.\r
\r
***Note:** If true, then this location is set as the default one. Otherwise, it is set to false.*", "nullable": true, "example": false }, "Address": { "$ref": "#/components/schemas/AddShippingLocationAddress" } }, "additionalProperties": false, "description": "Shipping Location Add" }, "AddShippingLocationResponse": { "type": "object", "properties": { "ShippingLocationId": { "type": "string", "description": "A unique identifier for the shipping location assigned by the system (shippingLocationId), allowing users to reference and manage specific locations effectively.", "format": "uuid" } }, "additionalProperties": false, "description": "Create Shipping Location Response" }, "Address": { "required": [ "Line1", "Town" ], "type": "object", "properties": { "Line1": { "minLength": 1, "type": "string", "description": "The first line of address of the PUDO location, typically containing the primary address information, such as house number and street name.", "example": "114-120 Camden High Street" }, "Line2": { "type": "string", "description": "An optional second line of address of the PUDO location, often used for additional details like apartment numbers or suite designations.", "nullable": true, "example": "Camden Town" }, "Line3": { "type": "string", "description": "A third optional line of address of the PUDO location for further specifications, allowing for more detailed address information if necessary.", "nullable": true }, "Town": { "minLength": 1, "type": "string", "description": "The town or city of the PUDO location, indicating the specific locality where the PUDO location is situated.", "example": "London" }, "Postcode": { "type": "string", "description": "The postal or ZIP code corresponding to the PUDO location's address, used for mail sorting and to identify the geographical area.", "nullable": true, "example": "TW18 4QR" }, "Geolocation": { "$ref": "#/components/schemas/Geolocation" }, "OpeningHours": { "$ref": "#/components/schemas/OpeningHours" } }, "additionalProperties": false, "description": "The complete address information of the PUDO locations, containing further details necessary for users to find and access the locations." }, "AddressBookList": { "required": [ "CountryCode", "Line1", "Town" ], "type": "object", "properties": { "AddressId": { "maxLength": 70, "type": "string", "description": "A unique identifier for each address record. This information ensures that each address can be distinctly referenced and managed within the system.", "nullable": true, "example": "John Brown Default" }, "ContactName": { "maxLength": 50, "type": "string", "description": "The name of the primary contact associated with the address. This field is essential for identification and communication purposes.", "nullable": true, "example": "Jane Doe" }, "CompanyName": { "maxLength": 50, "type": "string", "description": "The name of the company linked to the address. This field provides context for the address, especially in business-related queries.", "nullable": true, "example": "My Company Ltd." }, "ContactEmail": { "maxLength": 254, "type": "string", "description": "The email address of the primary contact for the address. This is used for correspondence and can facilitate communication directly related to the address.", "format": "email", "nullable": true, "example": "jane@example.com" }, "ContactPhone": { "maxLength": 20, "type": "string", "description": "The phone number of the primary contact associated with the address. This field is crucial for any immediate communication needs.", "format": "tel", "nullable": true }, "Line1": { "maxLength": 50, "minLength": 1, "type": "string", "description": "The first line of the address, typically containing the primary address information such as house number and street name.", "example": "10 Sky Lane" }, "Line2": { "maxLength": 50, "type": "string", "description": "An optional second line for the address, often used for additional details like apartment numbers or suite designations.", "nullable": true }, "Line3": { "maxLength": 50, "type": "string", "description": "A third optional line in the address to include any further address specifications, allowing for more detailed address information if necessary.", "nullable": true }, "Town": { "maxLength": 50, "minLength": 1, "type": "string", "description": "The town or city, indicating the specific locality where the address is located." }, "Postcode": { "maxLength": 20, "type": "string", "description": "The postal or ZIP code corresponding to the address, used to identify specific geographic areas.", "nullable": true }, "County": { "maxLength": 50, "type": "string", "description": "The county, state, or province in which the address is located, providing additional geographical context for the address.", "nullable": true }, "CountryCode": { "maxLength": 2, "minLength": 2, "type": "string", "description": "An abbreviation representing the country of the address, following the ISO 3166-1 alpha-2 standard, for example, \"GB\" for the United Kingdom.", "example": "GB" }, "What3Words": { "type": "string", "description": "A three-word location identifier provided by the What3words service, offering a precise way to define addresses using a unique combination of three words, for example, the front door of 10 Downing Street in London is identified by slurs.this.shark.", "nullable": true, "example": "brick.space.employ" }, "LastUpdatedDateUtc": { "type": "string", "description": "A timestamp in Coordinated Universal Time (UTC) indicating when the address record was last updated.This helps users understand the recency of the address information.", "format": "date-time", "example": "2022-02-06T16:13:24.010Z" }, "LastUpdatedBy": { "type": "string", "description": "The identifier of the user or system that last modified the address details, ensuring accountability and traceability for updates.", "nullable": true } }, "additionalProperties": false, "description": "Address Book List" }, "AddressBookPagedResponse": { "required": [ "Addresses", "TotalCount" ], "type": "object", "properties": { "Addresses": { "type": "array", "items": { "$ref": "#/components/schemas/AddressBookList" }, "description": "An array that contains the individual address records retrieved by the API. Each record includes detailed information about a specific address and its associated contact details." }, "TotalCount": { "type": "integer", "description": "An integer representing the total number of address records that match the search criteria. This count provides users with an overview of how many address records are available based on the filters applied.", "format": "int32" } }, "additionalProperties": false, "description": "The paged response containing the entities for the requested page only, and the total number available." }, "AddressBookSortBy": { "enum": [ "ContactName", "CompanyName", "Town", "CountryCode", "ContactEmail", "LastModified" ], "type": "string", "description": "Sort By" }, "Carrier": { "required": [ "CarrierCode", "Description", "Name" ], "type": "object", "properties": { "CarrierCode": { "maxLength": 10, "minLength": 1, "type": "string", "description": "A unique identifier for this carrier. This code is typically alphanumeric and serves as a reference to distinguish between various carriers within the system.", "example": "RM" }, "Name": { "minLength": 1, "type": "string", "description": "The official name of the carrier that provides users with a clear understanding of the carrier's identity.", "example": "Royal Mail" }, "Description": { "minLength": 1, "type": "string", "description": "A detailed overview of the carrier's services, capabilities, and distinguishing features. This field provides additional information about the carrier, helping users understand their offerings and operational scope.", "example": "Produces labels, required documentation, billing management for shipments sent via the Royal Mail network." } }, "additionalProperties": false, "description": "Carrier" }, "CarrierDetailed": { "required": [ "CarrierCode", "Description", "LogoBase64", "LogoFormat", "Name" ], "type": "object", "properties": { "CarrierCode": { "maxLength": 10, "minLength": 1, "type": "string", "description": "A unique identifier for this carrier. This code is typically alphanumeric and serves as a reference to distinguish between various carriers within the system.", "example": "RM" }, "Name": { "minLength": 1, "type": "string", "description": "The official name of the carrier that provides users with a clear understanding of the carrier's identity.", "example": "Royal Mail" }, "Description": { "minLength": 1, "type": "string", "description": "A detailed overview of the carrier's services, capabilities, and distinguishing features. This field provides additional information about the carrier, helping users understand their offerings and operational scope.", "example": "Produces labels, required documentation, billing management for shipments sent via the Royal Mail network." }, "LogoFormat": { "$ref": "#/components/schemas/CarrierLogoFormat" }, "LogoBase64": { "minLength": 1, "type": "string", "description": "A Base64-encoded string of the carrier's logo image in the format specified in the **LogoFormat** object. This allows for the direct embedding of the logo within the system, eliminating the need for separate image retrieval.", "example": "R0lGODlhYQBBAPf/AOjMmdsqOP3hHPqtHfmcHf3RHLa+vfPy8fAAH/vBHfH..." }, "CarrierTimezone": { "type": "string", "description": "The timezone in which the carrier operates. This information is essential for scheduling and coordination, as it indicates the local time for the carrier's operations and services, for example, London/Europe.", "nullable": true, "example": "London/Europe" } }, "additionalProperties": false, "description": "Carrier Detailed" }, "CarrierLogoFormat": { "enum": [ "PNG", "JPG", "GIF" ], "type": "string", "description": "The format of the carrier's logo image, typically indicated by a file extension, for example PNG, JPG, and GIF. This informs the user about the type of image file that is used for the carrier's branding." }, "CarrierMaxPackageDimensions": { "required": [ "Height", "Length", "Width" ], "type": "object", "properties": { "Length": { "type": "number", "description": "The maximum length accepted for the package type, typically measured in units, such as centimeters or millimeters. For example, if the length is 48, this means packages should not exceed 48 units in length.", "format": "double", "example": 60 }, "Width": { "type": "number", "description": "The maximum width accepted for the package type, typically measured in units, such as centimeters or millimeters. For example, if the width is 24, this means packages should not be wider than 24 units.", "format": "double", "example": 60 }, "Height": { "type": "number", "description": "The maximum height accepted for the package type, measured in units, such as centimeters or millimeters. For example, a height of 30 means the package cannot exceed 30 units in height.", "format": "double", "example": 60 }, "Combined": { "type": "number", "description": "The maximum combined dimensions that sums the length, width, and height of the package. These are often used to define space limitations for shipping. For example, if the combined maximum is 100, then the total length + width + height must not exceed 100 units.", "format": "double", "nullable": true, "example": 90 }, "DimensionsUnitOfMeasure": { "$ref": "#/components/schemas/DimensionsUnitOfMeasure" } }, "additionalProperties": false, "description": "The maximum allowable dimensions for packages in a carrier's service offering. It specifies the limits that must not be exceeded for packages to be eligible for specific shipping services." }, "CarrierService": { "required": [ "Description", "ServiceCode" ], "type": "object", "properties": { "ServiceCode": { "maxLength": 10, "minLength": 1, "type": "string", "description": "A unique identifier for each shipping service provided by the carrier. This code is typically alphanumeric and allows for easy reference and differentiation between various carrier services offered, for example, CRL1, TPM, and so on.", "example": "CRL1" }, "Description": { "maxLength": 100, "minLength": 1, "type": "string", "description": "A detailed explanation of the carrier service, outlining its features, benefits, and any pertinent conditions. This information helps understand the scope and specifics of what the service entails.", "example": "Royal Mail 24 Standard/Signed For (Parcel - Daily Rate Service)" } }, "additionalProperties": false, "description": "A unique identifier for each shipping service provided by the carrier. This code is typically alphanumeric and allows for easy reference and differentiation between various carrier services offered, for example, CRL1, TPM, and so on." }, "CarrierServicePackageType": { "required": [ "Description", "PackageTypeCode" ], "type": "object", "properties": { "PackageTypeCode": { "maxLength": 20, "minLength": 1, "type": "string", "description": "A unique identifier for each type of package offered by the carrier. For example, a code like \"BOX\" might represent a standard shipping box type, while \"ENVELOPE\" could refer to smaller package options.", "example": "LargeLetter" }, "Description": { "maxLength": 100, "minLength": 1, "type": "string", "description": "A brief overview of the package type, outlining its characteristics and intended use. For instance, a description might state, \"Medium box suitable for shipping small electronics,\" providing clarity on what items are best suited for that package.", "example": "Large Letter" }, "MaxWeight": { "type": "number", "description": "The maximum weight that a package can have to qualify for the specified package type.", "format": "double", "nullable": true, "example": 500 }, "WeightUnitOfMeasure": { "$ref": "#/components/schemas/WeightUnitOfMeasure" }, "MaxDimensions": { "type": "array", "items": { "$ref": "#/components/schemas/CarrierMaxPackageDimensions" }, "description": "The maximum allowable dimensions for packages in a carrier's service offering. It specifies the limits that must not be exceeded for packages to be eligible for specific shipping services.", "nullable": true } }, "additionalProperties": false, "description": "Carrier Service Package Type" }, "CommercialInvoiceRequest": { "required": [ "Document" ], "type": "object", "properties": { "InvoiceNumber": { "maxLength": 35, "type": "string", "description": "A unique identifier assigned to each commercial invoice, typically used for tracking and reference purposes.", "nullable": true }, "InvoiceDate": { "type": "string", "description": "The date when the commercial invoice was issued.\r
\r
***Note**: The invoice date must be in the YYYY-MM-DD format. If the date is not provided, it defaults to today's date.*", "format": "date", "nullable": true }, "Document": { "minLength": 1, "type": "string", "description": "The base64-encoded string of the document to be uploaded.\r
\r
***Note**: The max file size allowed for the encoded base64 PDF is 2MB.*", "example": "iVBORw0KGgoAAAANSUhEUgAA ... A4QAAAXcCAYAAAB6Q0CbAAAAAXNSR0IArs4" } }, "additionalProperties": false, "description": "Commercial Invoice Request" }, "Container": { "type": "object", "properties": { "ContainerId": { "type": "string", "description": "An identifier for the shipping container, important for managing cargo and logistics at scale.", "nullable": true, "example": "South East 1234" }, "ContainerStatus": { "$ref": "#/components/schemas/ContainerStatus" }, "CreatedDateUtc": { "type": "string", "description": "A timestamp indicating when each container was created, formatted in Coordinated Universal Time (UTC). This allows users to track the age and relevance of their container records.", "format": "date-time" }, "CarrierCode": { "type": "string", "description": "The unique identifier for the carrier associated with each container. This confirms which carrier is linked to the container, essential for logistics tracking.", "nullable": true, "example": "RM" }, "ShippingLocationId": { "type": "string", "description": "A unique identifier for the shipping location assigned by the system from which the container originates. With it, you can track and manage containers by a particular location.", "nullable": true, "example": "93f6d928-9456-434a-9d69-60f3b7dea091" }, "ShippingLocationAlias": { "type": "string", "description": "A unique user-defined identifier for the shipping location associated with the container, making it easier to reference and identify locations.", "nullable": true, "example": "Northern Warehouse" }, "TotalWeight": { "type": "number", "description": "The total weight of the shipments contained within the shipping container. This value is essential for understanding the logistics and capacity of the container.", "format": "double", "example": 12.5 }, "WeightUnitOfMeasure": { "$ref": "#/components/schemas/WeightUnitOfMeasure" }, "TotalShipments": { "type": "integer", "description": "The total number of shipments contained within the specified container. This field helps users understand the shipping capacity and complexity of the container.", "format": "int32", "example": 23 }, "TotalPackages": { "type": "integer", "description": "An integer representing the total number of packages contained within the shipments linked to the container. This information helps users understand the volume of packages being transported.", "format": "int32", "example": 23 } }, "additionalProperties": false, "description": "Container" }, "ContainerShipments": { "type": "object", "properties": { "TrackingNumber": { "type": "string", "description": "A unique identifier assigned to each shipment linked to the container, allowing users to track the progress and status of the shipment during transit.", "nullable": true, "example": "TT000860906GB" }, "BarcodeNumber": { "type": "string", "description": "A unique barcode associated with each shipment within the container, used for scanning and tracking purposes throughout the shipping process, enabling efficient handling and verification.", "nullable": true, "example": "4C0069786000000014AC0" }, "Reference1": { "type": "string", "description": "The shipper's reference for this shipment. This is usually the shipper's order number that is provided to the consumer when the order was made.", "nullable": true, "example": "OrderRef71" }, "ManifestNumber": { "type": "string", "description": "A unique identifier assigned to a shipping manifest.\r
\r
***Note:** This field is only populated if the container has been manifested.*", "nullable": true } }, "additionalProperties": false, "description": "An array of shipments associated with the container. Each shipment object contains details about the specific shipments that have been allocated to the container, providing comprehensive tracking and management data.\r
\r
***Note**: This information is provided only if the **returnShipments** field is set to true in the query parameters request.*" }, "ContainerStatus": { "enum": [ "Active", "Manifested" ], "type": "string", "description": "Indicates the current status of the container, providing information on whether it is active or manifested." }, "ContainerStatusForFiltering": { "enum": [ "Active", "Manifested", "All" ], "type": "string", "description": "Container Status" }, "ContainersPagedResponse": { "required": [ "Containers", "TotalCount" ], "type": "object", "properties": { "Containers": { "type": "array", "items": { "$ref": "#/components/schemas/Container" }, "description": "An array containing all shipping containers associated with the carrier and/or shipping location requested for the specific page only. Each object contains details about individual containers, such as identifiers and associated shipment data." }, "TotalCount": { "type": "integer", "description": "An integer indicating the total number of containers that match the query criteria. This count provides you with an overview of how many container records are available in the system based on the filters applied.", "format": "int32", "example": 32 } }, "additionalProperties": false, "description": "The paged response containing the entities for the requested page only, and the total number available." }, "ContainersSortBy": { "enum": [ "CreatedDateUtc", "ContainerId", "CarrierCode", "ShippingLocationAlias", "TotalWeight", "TotalShipments", "TotalPackages" ], "type": "string", "description": "Sort By" }, "CountriesPagedResponse": { "required": [ "Countries", "TotalCount" ], "type": "object", "properties": { "Countries": { "type": "array", "items": { "$ref": "#/components/schemas/Country" }, "description": "An array containing the individual country records retrieved by the API.\r
Each record includes detailed information about a specific country." }, "TotalCount": { "type": "integer", "description": "An integer representing the total number of countries matching the search criteria, regardless of pagination.\r
This information is useful for understanding the full scope of available results.", "format": "int32", "example": 236 } }, "additionalProperties": false, "description": "The paged response containing the entities for the requested page only, and the total number available." }, "CountriesSortBy": { "enum": [ "CountryName", "Alpha2Code", "Alpha3Code", "Numeric", "CountryGroup", "PostcodeRequired", "StateCodeRequired", "DefaultCurrency" ], "type": "string", "description": "Sort By" }, "Country": { "required": [ "Alpha2Code", "Alpha3Code", "CountryGroup", "CountryName", "DefaultCurrency", "Numeric", "PostcodeRequired", "StateCodeRequired" ], "type": "object", "properties": { "CountryName": { "minLength": 1, "type": "string", "description": "The official name of the country. \r
This field is crucial for identifying countries within the response.", "example": "United Kingdom" }, "Alpha2Code": { "maxLength": 2, "minLength": 2, "type": "string", "description": "A two-letter country code (ISO 3166-1 alpha-2) that uniquely identifies the country. \r
This code is widely used in various international standards and systems.", "example": "GB" }, "Alpha3Code": { "maxLength": 3, "minLength": 3, "type": "string", "description": "A three-letter country code (ISO 3166-1 alpha-3) that provides a separate unique identifier for the country. \r
This code can be useful for more detailed country representation.", "example": "GBR" }, "Numeric": { "maxLength": 3, "minLength": 3, "type": "string", "description": "A numeric code (ISO 3166-1 numeric) assigned to each country. \r
This code is utilised in the system for identifying the countries numerically.", "example": "826" }, "CountryGroup": { "$ref": "#/components/schemas/CountryGroup" }, "PostcodeRequired": { "type": "boolean", "description": "A boolean value indicating whether a postal code is required for the country. \r
This field helps determine whether address validation includes postal code checks.", "example": true }, "StateCodeRequired": { "type": "boolean", "description": "A boolean value indicating whether state or province codes are required for the country. \r
This is particularly relevant for countries with sub-national divisions.", "example": false }, "DefaultCurrency": { "maxLength": 3, "minLength": 3, "type": "string", "description": "The currency used as the standard in the country. \r
This field provides clarity on monetary transactions and conversions.", "example": "GBP" } }, "additionalProperties": false, "description": "Country" }, "CountryGroup": { "enum": [ "ROW", "EU" ], "type": "string", "description": "Indicates the grouping of the country, such as \"ROW\" (Rest of World) or \"EU\" (European Union). \r
This categorisation is essential for understanding trade, regulatory, or geopolitical contexts." }, "CreateShipmentsToTrackRequest": { "required": [ "CarrierCode", "TrackingNumber" ], "type": "object", "properties": { "TrackingNumber": { "maxLength": 50, "minLength": 1, "type": "string", "description": "The tracking number assigned to the shipment by the carrier. This number is used to monitor the shipment's progress and location in transit." }, "ShipperReference": { "maxLength": 30, "type": "string", "description": "The shipper's reference for this shipment. This is usually the shipper's order number that is provided to the receiver when the order was made.", "nullable": true }, "CarrierCode": { "maxLength": 10, "minLength": 1, "type": "string", "description": "A unique identifier for the carrier associated with the shipping account. This code is typically alphanumeric and helps in identifying the specific carrier linked to the shipping account." }, "CountryCode": { "maxLength": 2, "minLength": 2, "type": "string", "description": "An abbreviation representing the country for the shipment, following the ISO 3166-1 alpha-2 standard, for example, \"GB\" for the United Kingdom.", "nullable": true }, "Postcode": { "maxLength": 20, "type": "string", "description": "The postal or ZIP code corresponding to the shipment's destination, used to identify specific geographic areas.", "nullable": true }, "AccountNumber": { "maxLength": 20, "type": "string", "description": "The number assigned to the shipping account by the carrier, typically used for tracking shipments and billing purposes.", "nullable": true, "example": "9912347707" }, "ShippingDate": { "type": "string", "description": "The date on which the shipment was sent. This information is important for tracking the timeline of delivery and for any time-sensitive shipment inquiries.\r
\r
***Note**: This information is required by some carriers. If this date is provided, then it must be in the YYYY-MM-DD format.*", "format": "date", "nullable": true }, "ServiceCode": { "maxLength": 10, "type": "string", "description": "The code representing the carrier's shipping service selected for the shipments.", "nullable": true } }, "additionalProperties": false, "description": "Create Shipment To Track Request" }, "CurrenciesPagedResponse": { "required": [ "Currencies", "TotalCount" ], "type": "object", "properties": { "Currencies": { "type": "array", "items": { "$ref": "#/components/schemas/Currency" }, "description": "An array containing the individual currency records retrieved by the API. \r
Each record includes detailed information about a specific currency." }, "TotalCount": { "type": "integer", "description": "An integer representing the total number of currencies matching the search criteria, regardless of pagination.\r
This information is useful for understanding the full scope of available results.", "format": "int32", "example": 245 } }, "additionalProperties": false, "description": "The paged response containing the entities for the requested page only, and the total number available." }, "CurrenciesSortBy": { "enum": [ "CurrencyName", "CurrencyCode" ], "type": "string", "description": "Sort By" }, "Currency": { "required": [ "CurrencyCode", "CurrencyName" ], "type": "object", "properties": { "CurrencyName": { "minLength": 1, "type": "string", "description": "The official name of the currency. \r
This field is important for identifying currencies within the response and can help users understand the currency's usage.", "example": "Pound Sterling" }, "CurrencyCode": { "maxLength": 3, "minLength": 3, "type": "string", "description": "A three-letter code (ISO 4217) assigned to each currency, which uniquely identifies it in international standards. \r
This code is commonly used in financial transactions and currency exchanges.", "example": "GBP" } }, "additionalProperties": false, "description": "Currency" }, "DeferShipmentRequest": { "required": [ "ShipmentDate", "ShipmentId" ], "type": "object", "properties": { "ShipmentId": { "maxLength": 36, "minLength": 1, "type": "string", "description": "A unique identifier for the shipment that is being deferred. This ID is necessary to specify which shipment the new deferred status applies to, ensuring precise handling of the request.", "example": "AD123456783GB" }, "ShipmentDate": { "type": "string", "description": "A new date assigned to the shipment indicating when it is now scheduled to be manifested and shipped (handed over to the carrier). This field allows users to adjust their shipping timelines and effectively manage their logistics according to updated requirements or circumstances.\r
\r
Before entering the new shipment date, keep in mind the following:\r
• The date must be in the YYYY-MM-DD format.\r
• The date must not be in the past and cannot be more than 28 days in the future.", "format": "date" } }, "additionalProperties": false, "description": "Defer Shipment Request" }, "DimensionsUnitOfMeasure": { "enum": [ "CM", "MM" ], "type": "string", "description": "The unit of measure used for all the dimensions (length, width, height) values of the packages being shipped, allowing for measurements in millimeters and centimeters. This ensures consistency in how dimensions are handled.\r
\r
***Note:** By default, this field is set to CM.*" }, "DocumentType": { "enum": [ "CN23", "PI", "CI" ], "type": "string", "description": "Specifies the type of document being requested for printing. Common types include the following: \r
\r
***Note**: By default, this field is set to CN23.*" }, "EnhancedLocationDetails": { "type": "object", "properties": { "LocationType": { "type": "string", "description": "Indicates the type of location where parcels can be collected or dropped off.\r
Valid values are the following: \r
", "nullable": true, "example": "POL" }, "Supplier": { "type": "string", "description": "Indicates the name of the supplier associated with the specific location type, for example, PSH (RMShop).", "nullable": true, "example": "Collect+" }, "SupplierLocationType": { "type": "string", "description": "A categorisation that indicates the specific type of supplier location, providing additional context about the additional options available at that location, for example, RMShop.", "nullable": true, "example": "Locker" }, "LabelId": { "type": "string", "description": "A unique identifier for the Local Collect label and Pre-advice associated with the shipments at the location, which may be used for tracking and processing purposes.", "nullable": true }, "DistanceFromPostcode": { "type": "number", "description": "The distance from the specified postcode to the PUDO location, giving customers an indication of how far the location is from your desired address.", "format": "double", "nullable": true, "example": 1.4 }, "DistanceUnit": { "type": "string", "description": "The unit for the distance specified in the **DistanceFromPostcode** field.\r
\r
***Note**: By default, this field only returns the unit in miles.*", "nullable": true, "example": "miles" }, "SupplementCode": { "type": "string", "description": "A specific code that represents the type of location associated with a PUDO (Pick Up Drop Off) point. This code is essential in the pre-advice for shipments and indicates the type of PUDO location. However, when using the Create Shipment request, this code is automatically added based on the selected PUDO location.\r
\r
The codes may include the following with their associated suppliers:\r
", "nullable": true }, "LocationAvailableFeatures": { "$ref": "#/components/schemas/LocationAvailableFeatures" }, "LocationRestrictions": { "$ref": "#/components/schemas/LocationRestrictions" } }, "additionalProperties": false, "description": "This object provides detailed information on the PUDO location for the requested service.\r
\r
***Note**: This information is only provided if the **enhancedLocationDetails** field in the query parameter is set to true.*" }, "ErrorDetail": { "type": "object", "properties": { "Message": { "type": "string", "nullable": true }, "Cause": { "type": "string", "nullable": true }, "ErrorCode": { "type": "string", "description": "

**E1000** - System error
**E1001** - Required field
**E1002** - Invalid field
**E1003** - Invalid action
**E1004** - Item not found
", "nullable": true } }, "additionalProperties": false }, "ErrorResponse": { "required": [ "Errors", "Message" ], "type": "object", "properties": { "Message": { "minLength": 1, "type": "string" }, "Errors": { "type": "array", "items": { "$ref": "#/components/schemas/ErrorDetail" } } }, "additionalProperties": false }, "Geolocation": { "type": "object", "properties": { "Longitude": { "type": "number", "description": "The longitude of the PUDO location, expressed in degrees. This value aids in accurately locating the position on a map.\r
\r
***Note**: This value is only returned for carriers that provide this information.*", "format": "double", "example": -0.51174 }, "Latitude": { "type": "number", "description": "The latitude of the PUDO location, expressed in degrees. This value, along with Longitude, allows for precise mapping of the location.", "format": "double", "example": 51.43341 } }, "additionalProperties": false, "description": "An object representing the geographical coordinates of the PUDO location, providing precise location data necessary for navigation and mapping." }, "GetContainerResponse": { "type": "object", "properties": { "ContainerId": { "type": "string", "description": "An identifier for the shipping container, important for managing cargo and logistics at scale.", "nullable": true, "example": "South East 1234" }, "ContainerStatus": { "$ref": "#/components/schemas/ContainerStatus" }, "CreatedDateUtc": { "type": "string", "description": "A timestamp indicating when each container was created, formatted in Coordinated Universal Time (UTC). This allows users to track the age and relevance of their container records.", "format": "date-time" }, "ManifestNumbers": { "type": "array", "items": { "type": "string" }, "description": "Unique identifiers for the manifests associated with the container. This field is populated only if the container has been manifested, ensuring seamless audit trails and helps customers verify and track the overall shipment manifest that includes all shipments within the container.", "nullable": true }, "CarrierCode": { "type": "string", "description": "The unique identifier for the carrier associated with each container. This confirms which carrier is linked to the container, essential for logistics tracking.", "nullable": true, "example": "RM" }, "ShippingLocationId": { "type": "string", "description": "A unique identifier for the shipping location assigned by the system from which the container originates. With it, you can track and manage containers by a particular location.", "nullable": true, "example": "93f6d928-9456-434a-9d69-60f3b7dea091" }, "ShippingLocationAlias": { "type": "string", "description": "A unique user-defined identifier for the shipping location associated with the container, making it easier to reference and identify locations.", "nullable": true, "example": "Northern Warehouse" }, "TotalWeight": { "type": "number", "description": "The total weight of the shipments contained within the shipping container. This value is essential for understanding the logistics and capacity of the container.", "format": "double", "example": 12.5 }, "WeightUnitOfMeasure": { "$ref": "#/components/schemas/WeightUnitOfMeasure" }, "TotalShipments": { "type": "integer", "description": "The total number of shipments contained within the specified container. This field helps users understand the shipping capacity and complexity of the container.", "format": "int32", "example": 23 }, "TotalPackages": { "type": "integer", "description": "An integer representing the total number of packages contained within the shipments linked to the container. This information helps users understand the volume of packages being transported.", "format": "int32", "example": 23 }, "Shipments": { "type": "array", "items": { "$ref": "#/components/schemas/ContainerShipments" }, "description": "An array of shipments associated with the container. Each shipment object contains details about the specific shipments that have been allocated to the container, providing comprehensive tracking and management data.\r
\r
***Note**: This information is provided only if the **returnShipments** field is set to true in the query parameters request.*", "nullable": true } }, "additionalProperties": false, "description": "Get Container Response" }, "GetPudoLocationsResponse": { "type": "object", "properties": { "Locations": { "type": "array", "items": { "$ref": "#/components/schemas/Location" }, "description": "An array of locations that match the criteria specified in the request. Each object contains details about individual locations available for pick-up or drop-off services.", "nullable": true }, "TotalCount": { "type": "integer", "description": "An integer representing the total number of PUDO locations that match the specified query criteria. This provides users with an overview of how many PUDO locations are available on the system, enabling better understanding of the dataset.", "format": "int32", "example": 10 } }, "additionalProperties": false, "description": "Get PUDO Locations response" }, "GetShipmentsStatusType": { "enum": [ "Created", "OnHold", "Cancelled", "ReadyToPrint", "LabelPrinted", "Confirmed", "Picked" ], "type": "string", "description": "Get Shipments Status Type" }, "HazmatUnitOfMeasure": { "enum": [ "NONE", "L", "KG" ], "type": "string", "description": "The unit of measurement for the quantity of hazardous material, for example, litres (for liquids) or kilograms (for solids). This provides clarity regarding the amount of hazardous goods present.\r
***Note:** This field is only required if **Quantity** and **UNCode** is specified.*" }, "Location": { "required": [ "CarrierCode", "LocationAlias", "LocationId" ], "type": "object", "properties": { "CarrierCode": { "minLength": 1, "type": "string", "description": "The unique identifier representing the carrier associated with each PUDO location. This field ensures that the returned locations correspond to the specified carrier in the request.", "example": "RM" }, "LocationAlias": { "minLength": 1, "type": "string", "description": "A unique user-defined identifier for the PUDO location, providing a convenient way to identify it, for example, Downtown Drop-off or Main Street Pick-up.", "example": "Post office limited" }, "LocationId": { "minLength": 1, "type": "string", "description": " A unique identifier for each PUDO location assigned by the system. This ID allows for easy reference and management of specific locations.\r
\r
***Note**: For Royal Mail, this value will be the postcode of the post office.*", "example": "" }, "Address": { "$ref": "#/components/schemas/Address" }, "EnhancedLocationDetails": { "$ref": "#/components/schemas/EnhancedLocationDetails" } }, "additionalProperties": false, "description": "Location" }, "LocationAvailableFeatures": { "type": "object", "properties": { "ServiceCode": { "type": "string", "description": "Identifies the specific carrier shipping service that can be utilised at the local collect location, for example, TPN, TPS, ITL, and so on, allowing customers to understand the service options available for their parcels.", "nullable": true, "example": "TPN" }, "AcceptSignature": { "type": "boolean", "description": "Indicates whether the location is capable of accepting parcels that require a signature upon collection, ensuring that customers know which location can accommodate their signing requirements.", "nullable": true }, "AcceptNonSignature": { "type": "boolean", "description": "Indicates whether the location accepts parcels that require a signature upon collection, giving customers flexibility in choosing their pickup options based on their specific needs.", "nullable": true }, "LocationServices": { "type": "string", "description": "Provides a list of services available at the location, which may include the following: \r
", "nullable": true, "example": "pickup|dropoff|printinstore" }, "Facilities": { "type": "string", "description": "Provides information about any additional facilities available at the location, such as disabled access, parking, or other amenities, enhancing customer convenience.", "nullable": true, "example": "carparking|disabledaccess" } }, "additionalProperties": false, "description": "This object contains key details about the capabilities and services offered at each PUDO location." }, "LocationRestrictions": { "type": "object", "properties": { "MaxHeight": { "type": "number", "description": "The maximum height restriction for parcels accepted at the location, ensuring that items are within acceptable measurement limits, measured in centimeters.", "format": "double", "nullable": true }, "MaxWidth": { "type": "number", "description": "The maximum width restriction for parcels accepted at the location, providing guidance on the acceptable dimensions for incoming shipments, measured in centimeters.", "format": "double", "nullable": true }, "MaxLength": { "type": "number", "description": "The maximum length restriction for parcels accepted at the location, indicating the longest dimension acceptable for parcels at the location, measured in centimeters.", "format": "double", "nullable": true }, "MaxWeight": { "type": "number", "description": "The maximum weight limit for parcels that the location can handle, ensuring that heavier items are appropriately received and processed, measured in kilograms.", "format": "double", "nullable": true }, "MaxSize": { "type": "string", "description": "The maximum overall size restriction for parcels accepted at the location, for example, Small, Medium, Large, serving as a general guideline for the dimensional limits of parcels, ensuring compliance with the location's parcel acceptance policies.", "nullable": true, "example": "Medium" } }, "additionalProperties": false, "description": "This object outlines the limitations regarding parcel acceptance at each PUDO location. This object is critical for ensuring that customers are aware of the maximum allowable dimensions and weights for the parcels they intend to send or collect." }, "Manifest": { "required": [ "CarrierCode", "CreatedDateUtc", "ManifestDate", "ManifestNumber", "Service", "ShippingAccount", "ShippingLocation", "TotalItems", "TotalShipments", "TotalWeight", "WeightUnitOfMeasure" ], "type": "object", "properties": { "ManifestNumber": { "maxLength": 18, "minLength": 1, "type": "string", "description": "A unique identifier for the manifest, allowing for easy tracking and reference of the manifest document within the PRO SHIPPING system.", "example": "ISH2802532" }, "CarrierCode": { "maxLength": 10, "minLength": 1, "type": "string", "description": "The unique identifier of the carrier associated with the manifest. This confirms which shipping carrier's requirements the manifest adheres to.", "example": "RM" }, "Service": { "maxLength": 100, "minLength": 1, "type": "string", "description": "The shipping service selected for the manifest. If there are multiple services involved, the response will return a mixed designation, categorising the services used.", "example": "Mixed" }, "TotalWeight": { "type": "number", "description": "The total weight of all shipments included in the manifest, typically representing the combined weight of the packages being shipped.", "format": "double", "example": 545.612 }, "WeightUnitOfMeasure": { "$ref": "#/components/schemas/WeightUnitOfMeasure" }, "TotalShipments": { "type": "integer", "description": "The total number of shipments included in the manifest, providing a quick overview of how many shipments are being sent.", "format": "int32", "example": 562 }, "TotalItems": { "type": "integer", "description": "The total count of individual items (packages) within the shipments included in the manifest.", "format": "int32", "example": 562 }, "ManifestDate": { "type": "string", "description": "The date on which the manifest was created, offering a record of when the shipments were officially documented for shipping.", "format": "date", "example": "2024-07-16" }, "CreatedDateUtc": { "type": "string", "description": "A timestamp indicating when the manifest was created, formatted in Coordinated Universal Time (UTC), providing a standard reference for the creation of the document.", "format": "date-time", "example": "2024-07-16T09:20:54.397Z" }, "ShippingLocation": { "$ref": "#/components/schemas/ManifestShippingLocation" }, "ShippingAccount": { "$ref": "#/components/schemas/ManifestShippingAccount" } }, "additionalProperties": false, "description": "Manifest" }, "ManifestAsyncRequest": { "type": "object", "properties": { "ShippingLocationId": { "maxLength": 100, "type": "string", "description": "A unique identifier assigned by the system (**ShippingLocationId**) or by you (**LocationAlias**) for the shipping location from which the shipments are being manifested. This information is crucial for linking the manifest to the correct shipping point.", "nullable": true, "example": "D94E8CFD-604B-4B87-83E9-3F20CAF02837" }, "ContainerId": { "maxLength": 50, "type": "string", "description": "The identifier for the container that holds the shipments being manifested. This field is necessary when shipments grouped together in a container are being manifested.\r
\r
***Note**: This information is only required if you want to manifest a container. If provided, make sure to enter the **Shipping Location**, as all other values are not applicable for this field. Prior to manifesting a container, ensure that you have created one and added the desired shipments to it.*", "nullable": true }, "Status": { "$ref": "#/components/schemas/ManifestShipmentStatus" }, "ShippingAccountId": { "maxLength": 36, "type": "string", "description": "A unique identifier assigned by the PRO SHIPPING system for the shipping account associated with the shipments. This information is important for billing and tracking purposes, connecting the manifest to the correct account. If needed, provide this information if you want to manifest shipments by a specific shipping account only.\r
\r
***Note**: This information is not valid when manifesting shipments by container.*", "nullable": true, "example": "88470398-A520-4069-BDF9-69D11D48831A" }, "ServiceCode": { "maxLength": 10, "type": "string", "description": "The code representing the carrier's shipping service selected for the shipments. If needed, provide the desired service code if you want to manifest shipments by a specific service only.\r
\r
***Note**: This information is not valid when manifesting shipments by container.*", "nullable": true, "example": "EXPRESS" } }, "additionalProperties": false, "description": "Manifest Async Request" }, "ManifestDetailsResponse": { "required": [ "CarrierCode", "CreatedDateUtc", "ManifestDate", "ManifestNumber", "Service", "Shipments", "ShippingAccount", "ShippingLocation", "TotalItems", "TotalShipments", "TotalWeight", "WeightUnitOfMeasure" ], "type": "object", "properties": { "ManifestNumber": { "maxLength": 18, "minLength": 1, "type": "string", "description": "A unique identifier for the manifest, allowing for easy tracking and reference of the manifest document within the PRO SHIPPING system.", "example": "ISH2802532" }, "CarrierCode": { "maxLength": 10, "minLength": 1, "type": "string", "description": "The unique identifier of the carrier associated with the manifest. This confirms which shipping carrier's requirements the manifest adheres to.", "example": "RM" }, "Service": { "maxLength": 100, "minLength": 1, "type": "string", "description": "The shipping service selected for the manifest. If there are multiple services involved, the response will return a mixed designation, categorising the services used.", "example": "Mixed" }, "TotalWeight": { "type": "number", "description": "The total weight of all shipments included in the manifest, typically representing the combined weight of the packages being shipped.", "format": "double", "example": 545.612 }, "WeightUnitOfMeasure": { "$ref": "#/components/schemas/WeightUnitOfMeasure" }, "TotalShipments": { "type": "integer", "description": "The total number of shipments included in the manifest, providing a quick overview of how many shipments are being sent.", "format": "int32", "example": 562 }, "TotalItems": { "type": "integer", "description": "The total count of individual items (packages) within the shipments included in the manifest.", "format": "int32", "example": 562 }, "ManifestDate": { "type": "string", "description": "The date on which the manifest was created, offering a record of when the shipments were officially documented for shipping.", "format": "date", "example": "2024-07-16" }, "CreatedDateUtc": { "type": "string", "description": "A timestamp indicating when the manifest was created, formatted in Coordinated Universal Time (UTC), providing a standard reference for the creation of the document.", "format": "date-time", "example": "2024-07-16T09:20:54.397Z" }, "ShippingLocation": { "$ref": "#/components/schemas/ManifestShippingLocation" }, "ShippingAccount": { "$ref": "#/components/schemas/ManifestShippingAccount" }, "Shipments": { "type": "array", "items": { "$ref": "#/components/schemas/ManifestShipment" }, "description": "An array of shipment objects contained within the specified manifest. Each shipment object provides detailed information about the individual shipments included in that manifest, such as tracking number, barcode number, and reference." } }, "additionalProperties": false, "description": "Manifest Details Response" }, "ManifestRequest": { "type": "object", "properties": { "ShippingLocationId": { "maxLength": 100, "type": "string", "description": "A unique identifier assigned by the system (**ShippingLocationId**) or by you (**LocationAlias**) for the shipping location from which the shipments are being manifested. This information is crucial for linking the manifest to the correct shipping point.", "nullable": true, "example": "D94E8CFD-604B-4B87-83E9-3F20CAF02837" }, "ContainerId": { "maxLength": 50, "type": "string", "description": "The identifier for the container that holds the shipments being manifested. This field is necessary when shipments grouped together in a container are being manifested.\r
\r
***Note**: This information is only required if you want to manifest a container. If provided, make sure to enter the **Shipping Location**, as all other values are not applicable for this field. Prior to manifesting a container, ensure that you have created one and added the desired shipments to it.*", "nullable": true }, "Status": { "$ref": "#/components/schemas/ManifestShipmentStatus" }, "ShippingAccountId": { "maxLength": 36, "type": "string", "description": "A unique identifier assigned by the PRO SHIPPING system for the shipping account associated with the shipments. This information is important for billing and tracking purposes, connecting the manifest to the correct account. If needed, provide this information if you want to manifest shipments by a specific shipping account only.\r
\r
***Note**: This information is not valid when manifesting shipments by container.*", "nullable": true, "example": "88470398-A520-4069-BDF9-69D11D48831A" }, "ServiceCode": { "maxLength": 10, "type": "string", "description": "The code representing the carrier's shipping service selected for the shipments. If needed, provide the desired service code if you want to manifest shipments by a specific service only.\r
\r
***Note**: This information is not valid when manifesting shipments by container.*", "nullable": true, "example": "EXPRESS" }, "Async": { "type": "boolean", "description": "A boolean value indicating whether you want to execute the manifest request asynchronously. If set to true, the API will respond immediately with an OK status. The manifest will be processed in the background, allowing you to retrieve the manifest once the processing is complete." } }, "additionalProperties": false, "description": "Manifest Request" }, "ManifestRequestStatus": { "enum": [ "Pending", "InProgress", "Complete", "Failed" ], "type": "string" }, "ManifestRequestStatusResponse": { "type": "object", "properties": { "FailedReason": { "$ref": "#/components/schemas/ErrorResponse" }, "ManifestCount": { "type": "integer", "description": "Total number of manifests created when the manifest request status is complete.", "format": "int32" }, "ManifestRequestId": { "type": "string", "description": "A unique identifier assigned by the system that specifies the manifest request.", "format": "uuid" }, "ManifestRequestStatus": { "type": "string", "description": "Indicates the current status of the manifest request.\r
\r
***Note**: By default, the status is set to Pending.*", "nullable": true }, "Manifests": { "type": "array", "items": { "$ref": "#/components/schemas/ManifestResponse" }, "description": "An array of manifest objects for the requested page only, matching the query criteria. Each object contains detailed information about individual manifests, such as associated shipments, dates, service, and others.", "nullable": true } }, "additionalProperties": false, "description": "Manifest Details Response" }, "ManifestResponse": { "required": [ "CarrierCode", "CreatedDateUtc", "ManifestDate", "ManifestImage", "ManifestNumber", "Service", "ShippingAccount", "ShippingLocation", "TotalItems", "TotalShipments", "TotalWeight", "WeightUnitOfMeasure" ], "type": "object", "properties": { "ManifestImage": { "minLength": 1, "type": "string", "description": "The generated manifest document returned as a Base64-encoded PDF. This image represents the finalised version of the shipping manifest based on the submitted details.", "example": "jVBERw0KGgoAAAANSUhEUgAA.....A4QAAAXcCAYAAAB6Q0CbAAAAAXNSR0IArs4" }, "ManifestNumber": { "maxLength": 18, "minLength": 1, "type": "string", "description": "A unique identifier for the manifest, allowing for easy tracking and reference of the manifest document within the PRO SHIPPING system.", "example": "ISH2802532" }, "CarrierCode": { "maxLength": 10, "minLength": 1, "type": "string", "description": "The unique identifier of the carrier associated with the manifest. This confirms which shipping carrier's requirements the manifest adheres to.", "example": "RM" }, "Service": { "maxLength": 100, "minLength": 1, "type": "string", "description": "The shipping service selected for the manifest. If there are multiple services involved, the response will return a mixed designation, categorising the services used.", "example": "Mixed" }, "TotalWeight": { "type": "number", "description": "The total weight of all shipments included in the manifest, typically representing the combined weight of the packages being shipped.", "format": "double", "example": 545.612 }, "WeightUnitOfMeasure": { "$ref": "#/components/schemas/WeightUnitOfMeasure" }, "TotalShipments": { "type": "integer", "description": "The total number of shipments included in the manifest, providing a quick overview of how many shipments are being sent.", "format": "int32", "example": 562 }, "TotalItems": { "type": "integer", "description": "The total count of individual items (packages) within the shipments included in the manifest.", "format": "int32", "example": 562 }, "ManifestDate": { "type": "string", "description": "The date on which the manifest was created, offering a record of when the shipments were officially documented for shipping.", "format": "date", "example": "2024-07-16" }, "CreatedDateUtc": { "type": "string", "description": "A timestamp indicating when the manifest was created, formatted in Coordinated Universal Time (UTC), providing a standard reference for the creation of the document.", "format": "date-time", "example": "2024-07-16T09:20:54.397Z" }, "ShippingLocation": { "$ref": "#/components/schemas/ManifestShippingLocation" }, "ShippingAccount": { "$ref": "#/components/schemas/ManifestShippingAccount" } }, "additionalProperties": false, "description": "Manifest Response" }, "ManifestShipment": { "required": [ "BarcodeNumber", "Reference1", "TrackingNumber" ], "type": "object", "properties": { "TrackingNumber": { "minLength": 1, "type": "string", "description": "A unique identifier assigned to each shipment within the manifest, allowing you to track the progress and status of that shipment during transit. This number is crucial for logistics and customer inquiries.", "example": "TT000860906GB" }, "BarcodeNumber": { "minLength": 1, "type": "string", "description": "A unique barcode associated with each shipment in the manifest. This barcode is used for scanning and tracking purposes throughout the shipping process, enabling efficient handling and verification of shipments.", "example": "4C0069786000000014AC0" }, "Reference1": { "minLength": 1, "type": "string", "description": "The shipper's reference for the shipments within the manifest. This is usually the shipper's order number that is provided to the receiver when the order was made.", "example": "OrderRef56" } }, "additionalProperties": false, "description": "Shipment\r
The shipment in this manifest." }, "ManifestShipmentStatus": { "enum": [ "Picked" ], "type": "string", "description": "Specifies the status of the shipments being manifested. The manifest can only be created for shipments with the **Picked** status, indicating that they are ready to be despatched. If this status is not specified, then all the shipments in either **LabelPrinted** or **Picked** status will be manifested.\r
\r
***Note**: This information is not valid when manifesting shipments by container.*" }, "ManifestShipmentsAsyncResponse": { "type": "object", "properties": { "ManifestRequestId": { "type": "string", "description": "The manifest request id", "nullable": true }, "ManifestRequestStatus": { "$ref": "#/components/schemas/ManifestRequestStatus" } }, "additionalProperties": false }, "ManifestShippingAccount": { "required": [ "AccountAlias", "AccountName", "ShippingAccountId" ], "type": "object", "properties": { "ShippingAccountId": { "type": "string", "description": "A unique identifier for each shipping account, allowing for efficient reference and management of individual accounts within the system.", "format": "uuid" }, "AccountName": { "maxLength": 35, "minLength": 1, "type": "string", "description": "The official name of the shipping account as designated by the user or organisation, aiding in easy identification and reference of accounts.", "example": "AB VideoGames" }, "AccountAlias": { "maxLength": 30, "minLength": 1, "type": "string", "description": "A user-defined name for the shipping account, providing a convenient way to reference the account in a more memorable manner.", "example": "Account 1" }, "AccountNumber": { "maxLength": 30, "type": "string", "description": "The number assigned to the shipping account by the carrier, typically used for tracking shipments and billing purposes.", "nullable": true, "example": "0123456789" } }, "additionalProperties": false, "description": "The shipping account associated with the shipments within the manifest." }, "ManifestShippingLocation": { "required": [ "LocationAlias", "LocationCountry", "ShippingLocationId" ], "type": "object", "properties": { "ShippingLocationId": { "type": "string", "description": "A unique identifier assigned by the system (ShippingLocationId) for the shipping location from which the shipments are being manifested. This information is crucial for linking the manifest to the correct shipping point.", "format": "uuid" }, "LocationAlias": { "maxLength": 100, "minLength": 1, "type": "string", "description": "A unique user-defined identifier for the shipping location, providing a convenient way to identify it, for example, Home or Warehouse.", "example": "Main Warehouse" }, "LocationCountry": { "maxLength": 2, "minLength": 2, "type": "string", "description": "An abbreviation representing the country of the shipping location, following the ISO 3166-1 alpha-2 standard, for example, \"GB\" for the United Kingdom, ensuring that users have clear geographical context for the shipments being manifested.", "example": "GB" }, "LocationPostcode": { "maxLength": 20, "type": "string", "description": "The postal or ZIP code corresponding to the shipping location, used for sorting and identifying the geographical area of the despatch.", "nullable": true, "example": "TW20 0HJ" } }, "additionalProperties": false, "description": "The shipping location from which the shipments are being manifested, offering additional context about where the shipments originate." }, "ManifestsPagedResponse": { "required": [ "Manifests", "TotalCount" ], "type": "object", "properties": { "Manifests": { "type": "array", "items": { "$ref": "#/components/schemas/Manifest" }, "description": "An array of manifest objects for the requested page only, matching the query criteria. Each object contains detailed information about individual manifests, such as associated shipments, dates, service, and others." }, "TotalCount": { "type": "integer", "description": "An integer representing the total number of manifests that match the specified query criteria.", "format": "int32", "example": 32 } }, "additionalProperties": false, "description": "Manifests Paged Response" }, "OpeningHours": { "type": "object", "properties": { "Monday": { "$ref": "#/components/schemas/OpeningHoursTime" }, "Tuesday": { "$ref": "#/components/schemas/OpeningHoursTime" }, "Wednesday": { "$ref": "#/components/schemas/OpeningHoursTime" }, "Thursday": { "$ref": "#/components/schemas/OpeningHoursTime" }, "Friday": { "$ref": "#/components/schemas/OpeningHoursTime" }, "Saturday": { "$ref": "#/components/schemas/OpeningHoursTime" }, "Sunday": { "$ref": "#/components/schemas/OpeningHoursTime" } }, "additionalProperties": false, "description": "Precise information regarding the operating hours of the PUDO location by each day of the week, specifying when the location is open or closed to customers for pick-up or drop-off services." }, "OpeningHoursTime": { "type": "object", "properties": { "OpeningTime": { "type": "string", "description": "The time when the PUDO location opens for business, providing users with essential information on when they can access the services.\r
\r
***Note**: This time is represented in the HH:MM:SS format.*", "nullable": true, "example": "09:00:00" }, "ClosingTime": { "type": "string", "description": "The time when the PUDO location closes for business, helping users understand the operational hours and plan their visits accordingly.\r
\r
***Note**: This time is represented in the HH:MM:SS format.*", "nullable": true, "example": "17:30:00" } }, "additionalProperties": false, "description": "The time when the PUDO location opens for business, providing users with essential information on when they can access the services.\r
\r
***Note**: This time is represented in the HH:MM:SS format.*" }, "OrderDirection": { "enum": [ "Ascending", "Descending" ], "type": "string", "description": "Order Direction" }, "PrintDocumentRequest": { "type": "object", "properties": { "DocumentType": { "$ref": "#/components/schemas/DocumentType" }, "NumberOfCopies": { "maximum": 5, "minimum": 1, "type": "integer", "description": "An integer indicating how many copies of the specified document should be printed. This allows users to request multiple copies for various purposes, such as retaining records or providing documentation to customs.\r
\r
***Note**: By default, this value is set to 1.*", "format": "int32", "default": 1 }, "EoriNumber": { "maxLength": 17, "type": "string", "description": "The Economic Operators Registration and Identification (EORI) number assigned to businesses for trading in the EU. This number is necessary for customs clearance processes.\r
\r
Shipper/Receiver's EORI number starts with the ISO Alpha-2 Country Code followed by a maximum of 15 alphanumeric characters. For Northern Ireland, it starts with XI, respectively.\r
\r
***Note**: If this information is provided, it overrides the shipper's EORI number on the shipment. Additionally, if both VAT and EORI numbers are provided, then only the EORI number is printed on the CN23.*", "nullable": true, "example": "GB23456789000" }, "VatNumber": { "maxLength": 15, "type": "string", "description": "The Value Added Tax (VAT) registration number of the business or individual, used for taxation purposes in international transactions.\r
\r
***Note**: If this information is provided, it overrides the shipper's VAT number on the shipment.*", "nullable": true, "example": "GB 123 4567 89" }, "ReasonForExport": { "maxLength": 30, "type": "string", "description": "Identifies the purpose of the export, such as sale, gift, or return. This information is useful for customs processing to determine the appropriate tariffs and requirements.\r
\r
If the carrier is associated with the Universal Postal Union (UPU), then the allowed reasons for export are the following:\r
\r
***Note**: Before populating this field, keep in mind the following:*\r
\r
", "nullable": true, "example": "Gift" }, "Name": { "maxLength": 40, "type": "string", "description": "The name of the individual (shipper) who is associated with the shipment. This personalises the documentation and can be important for official purposes.\r
\r
***Note**: If this information is provided, it overrides the shipment's shipper's company/contact name.*", "nullable": true, "example": "Jane Brown" }, "Position": { "maxLength": 50, "type": "string", "description": "The job title or position of the individual (shipper) named on the document. This information can add legitimacy and context to the document, especially if it is to be presented to authorities.\r
\r
***Note**: This field is only applicable for the proforma and commercial invoices. It is ignored for the CN23s.*", "nullable": true, "example": "Logistics Manager" }, "SignatureImage": { "type": "string", "description": "An image of the individual's signature, in the Base64 encoded PDF or JPEG format. This provides a digital representation of the signature, required on the customs documents for authenticity.\r
\r
***Note**: This field is only applicable for the proforma and commercial invoices. It is ignored for the CN23s.*", "nullable": true, "example": "iVBORw0KGgoAAAANSUhEUgAA ... A4QAAAXcCAYAAAB6Q0CbAAAAAXNSR0IArs4" }, "CompanyStampImage": { "type": "string", "description": "An image of the company stamp, in the Base64 PDF or JPEG format. This stamp can be used to validate the document and provide a formal presentation of the company's authority.\r
\r
***Note**: This field is only applicable for the proforma and commercial invoices. It is ignored for the CN23s.*", "nullable": true, "example": "iVBORw0KGgoAAAANSUhEUgAA ... A4QAAAXcCAYAAAB6Q0CbAAAAAXNSR0IArs4" } }, "additionalProperties": false, "description": "Print Document Request" }, "PrintDocumentResponse": { "required": [ "Document", "DocumentType" ], "type": "object", "properties": { "Document": { "minLength": 1, "type": "string", "description": "The generated document returned as a Base64-encoded PDF, ready for downloading or printing. This represents the finalized version of the requested shipping document based on the provided parameters.", "example": "iVBORw0KGgoAAAANSUhEUgAA ... A4QAAAXcCAYAAAB6Q0CbAAAAAXNSR0IArs4" }, "DocumentType": { "$ref": "#/components/schemas/PrintDocumentResponseDocumentType" } }, "additionalProperties": false, "description": "Print Document Response" }, "PrintDocumentResponseDocumentType": { "enum": [ "CN23", "PI", "CI" ], "type": "string", "description": "Specifies the type of document requested for printing. Common types include the following:\r
\r
***Note**: By default, this field is set to CN23.*" }, "Product": { "required": [ "CurrencyCode", "Description", "SkuCode", "Value", "Weight" ], "type": "object", "properties": { "SkuCode": { "maxLength": 30, "minLength": 1, "type": "string", "description": "A unique Stock Keeping Unit (SKU) code assigned to the product. This code is essential for tracking inventory, helping users identify specific products easily.", "example": "SKU123" }, "Description": { "maxLength": 255, "minLength": 1, "type": "string", "description": "A brief summary providing details about the product, outlining its features, uses, and any pertinent information that helps users understand the product.\r
\r
***Note**: If you use the data of the stored product in your create shipment requests, then this description will be used as the item description for customs purposes, detailing the specific item being shipped.*", "example": "White Men Large T-shirt" }, "Value": { "maximum": 9999999.99, "minimum": 0.01, "type": "number", "description": "The commercial value of the product. This field is important for inventory valuation and pricing strategies.", "format": "double", "example": 19.99 }, "Weight": { "maximum": 1000000, "minimum": 0.001, "minLength": 1, "type": "string", "description": "The weight of the individual product in the unit of measure specified in the **WeightUnitOfMeasure** field.", "example": "0.5" }, "HSCode": { "maxLength": 13, "minLength": 6, "type": "string", "description": "The Harmonized System (HS) code used by customs to determine potential duties and taxes for the product. This code can be 6, 8, or 13 alphanumeric characters, depending on specific services or destinations. Some countries may also use the HS codes of other character lengths, such as 10 characters.", "nullable": true, "example": "6109100010" }, "CountryOfOrigin": { "maxLength": 2, "minLength": 2, "type": "string", "description": "An abbreviation representing the country where the product was manufactured or produced, following the ISO 3166-1 alpha-2 standard, for example, \"GB\" for the United Kingdom. This information is important for customs declarations and compliance with import/export regulations.", "nullable": true, "example": "GB" }, "CurrencyCode": { "maxLength": 3, "minLength": 3, "type": "string", "description": "An abbreviation representing the 3 letter ISO currency code in which the product's **Value** is expressed (for example, \"GBP\" for British pounds, \"EUR\" for euros). This is essential for financial transactions and international trade.", "example": "GBP" }, "WeightUnitOfMeasure": { "$ref": "#/components/schemas/WeightUnitOfMeasure" }, "ManufactureProductId": { "maxLength": 50, "type": "string", "description": "A unique manufacturer identifier for the item being shipped, for example, proprietary manufacturer code, model number, or internal code.", "nullable": true }, "StandardisedProductId": { "maxLength": 50, "type": "string", "description": "A globally recognised product identifier for the item being shipped, for example, GTIN, EAN, and UPC.", "nullable": true }, "Hazmat": { "$ref": "#/components/schemas/ProductHazmat" } }, "additionalProperties": false, "description": "Product" }, "ProductHazmat": { "required": [ "Class" ], "type": "object", "properties": { "UNCode": { "maxLength": 4, "minLength": 4, "type": "string", "description": "The United Nations (UN) code assigned to the hazardous material, which denotes its classification for transport. This code is critical for safety and compliance during shipping.", "nullable": true, "example": "1002" }, "ProperShippingName": { "maxLength": 100, "type": "string", "description": "The official name designated for the hazardous material as required by regulations. This name is used to inform handlers of the nature of the hazard during transport.", "nullable": true, "example": "Compressed Air" }, "Class": { "maxLength": 3, "minLength": 1, "type": "string", "description": "The class number of the hazardous material as per UN regulations, indicating the potential risk associated with the product.", "example": "9" }, "Id8000Category": { "type": "string", "description": "A specific category designation used for certain hazardous materials classified under Class 9, providing additional regulatory requirements for handling and transport.\r
Available values are the following:\r
", "nullable": true, "example": "Nail Varnish" }, "Quantity": { "maximum": 5, "type": "number", "description": "The quantity of the hazardous material in the specified **UnitOfMeasure**. This information is vital for compliance with shipping regulations pertaining to hazardous materials.", "format": "double", "nullable": true, "example": 3.5 }, "UnitOfMeasure": { "$ref": "#/components/schemas/HazmatUnitOfMeasure" }, "EmergencyActionCode": { "maxLength": 4, "minLength": 4, "type": "string", "description": "A code providing emergency response instructions for handling hazardous materials during transport.This code is critical for safety and risk management.", "nullable": true, "example": "E012" }, "HazchemNumber": { "maxLength": 3, "minLength": 3, "type": "string", "description": "A number that indicates the type of hazardous material and the precautions necessary for its transport. This helps in emergency situations through quick identification.", "nullable": true }, "SpecialistAdviceContactNumber": { "maxLength": 20, "type": "string", "description": "A contact number for expert advice regarding the handling and transport of hazardous materials. This information is crucial during emergencies or if unusual situations arise.\r
\r
***Note:** If this information is not provided and the hazardous material is used in your **Create Shipment** request, then the contact number will be sent from the customer shipping account record.*", "nullable": true } }, "additionalProperties": false, "description": "Specifies the details whether the product is classified as hazardous material. This designation impacts shipping regulations and handling procedures." }, "ProductList": { "required": [ "CurrencyCode", "Description", "SkuCode", "Value", "Weight" ], "type": "object", "properties": { "LastUpdatedDateUtc": { "type": "string", "description": "A timestamp in Coordinated Universal Time (UTC) indicating when the product details were last updated. This helps users understand the recency of the product information.", "format": "date-time", "example": "2022-02-06T16:13:24.010Z" }, "LastUpdatedBy": { "type": "string", "description": "The identifier of the user or system that last modified the product details, ensuring accountability and traceability for updates.", "nullable": true, "example": "User A" }, "SkuCode": { "maxLength": 30, "minLength": 1, "type": "string", "description": "A unique Stock Keeping Unit (SKU) code assigned to the product. This code is essential for tracking inventory, helping users identify specific products easily.", "example": "SKU123" }, "Description": { "maxLength": 255, "minLength": 1, "type": "string", "description": "A brief summary providing details about the product, outlining its features, uses, and any pertinent information that helps users understand the product.\r
\r
***Note**: If you use the data of the stored product in your create shipment requests, then this description will be used as the item description for customs purposes, detailing the specific item being shipped.*", "example": "White Men Large T-shirt" }, "Value": { "maximum": 9999999.99, "minimum": 0.01, "type": "number", "description": "The commercial value of the product. This field is important for inventory valuation and pricing strategies.", "format": "double", "example": 19.99 }, "Weight": { "maximum": 1000000, "minimum": 0.001, "minLength": 1, "type": "string", "description": "The weight of the individual product in the unit of measure specified in the **WeightUnitOfMeasure** field.", "example": "0.5" }, "HSCode": { "maxLength": 13, "minLength": 6, "type": "string", "description": "The Harmonized System (HS) code used by customs to determine potential duties and taxes for the product. This code can be 6, 8, or 13 alphanumeric characters, depending on specific services or destinations. Some countries may also use the HS codes of other character lengths, such as 10 characters.", "nullable": true, "example": "6109100010" }, "CountryOfOrigin": { "maxLength": 2, "minLength": 2, "type": "string", "description": "An abbreviation representing the country where the product was manufactured or produced, following the ISO 3166-1 alpha-2 standard, for example, \"GB\" for the United Kingdom. This information is important for customs declarations and compliance with import/export regulations.", "nullable": true, "example": "GB" }, "CurrencyCode": { "maxLength": 3, "minLength": 3, "type": "string", "description": "An abbreviation representing the 3 letter ISO currency code in which the product's **Value** is expressed (for example, \"GBP\" for British pounds, \"EUR\" for euros). This is essential for financial transactions and international trade.", "example": "GBP" }, "WeightUnitOfMeasure": { "$ref": "#/components/schemas/WeightUnitOfMeasure" }, "ManufactureProductId": { "maxLength": 50, "type": "string", "description": "A unique manufacturer identifier for the item being shipped, for example, proprietary manufacturer code, model number, or internal code.", "nullable": true }, "StandardisedProductId": { "maxLength": 50, "type": "string", "description": "A globally recognised product identifier for the item being shipped, for example, GTIN, EAN, and UPC.", "nullable": true }, "Hazmat": { "$ref": "#/components/schemas/ProductHazmat" } }, "additionalProperties": false, "description": "Product List" }, "ProductsPagedResponse": { "required": [ "Products", "TotalCount" ], "type": "object", "properties": { "Products": { "type": "array", "items": { "$ref": "#/components/schemas/ProductList" }, "description": "An array containing all products that match the search criteria for the specific page only. Each object contains detailed information about individual products, including attributes necessary for identification and shipping." }, "TotalCount": { "type": "integer", "description": "An integer representing the total number of products that match the search criteria. This count provides users with an overview of how many product records are available based on the filters applied.", "format": "int32", "example": 32 } }, "additionalProperties": false, "description": "An array containing all products that match the search criteria for the specific page only. Each object contains detailed information about individual products, including attributes necessary for identification and shipping." }, "ProductsSortBy": { "enum": [ "Description", "Value", "HSCode", "SKU", "Weight", "Currency", "LastModified", "Country", "Category" ], "type": "string", "description": "Sort By" }, "ShipmentResponse": { "type": "object", "properties": { "ShippingAccountId": { "type": "string", "description": "A unique identifier for each shipping account assigned by the PRO SHIPPING system, allowing for efficient reference and management of individual accounts within the system.", "format": "uuid" }, "ShipmentId": { "type": "string", "description": "A unique identifier for each shipment. This ID is used to reference and track specific shipments within the system.", "format": "uuid" }, "TrackingNumber": { "type": "string", "description": "The tracking number assigned to the shipment by the carrier. This number is used to monitor the shipment's progress and location in transit.", "nullable": true }, "BarcodeNumber": { "type": "string", "description": "A unique barcode associated with the shipment, typically used for scanning and tracking purposes within logistics and shipping operations.", "nullable": true }, "Reference1": { "type": "string", "description": "The shipper's reference for this shipment. This is usually the shipper's order number that is provided to the receiver when the order was made.", "nullable": true }, "ShipmentDate": { "type": "string", "description": "The date the shipment was created or dispatched. This timestamp helps users track the timeline of the shipment.\r
\r
***Note**: The date must be in the YYYY-MM-DD format.*", "format": "date" }, "Status": { "type": "string", "description": "The current operational status of the shipment, similar to the **Status** field described earlier, providing insight into where the shipment stands in its delivery process.", "nullable": true }, "ManifestNumber": { "type": "string", "description": "A unique number assigned to the shipment's manifest, which includes a list of all packages contained in a shipment, aiding in tracking and accountability.\r
\r
***Note**: If the shipment has not been manifested, then this field returns as blank.*", "nullable": true }, "ContainerId": { "type": "string", "description": "An identifier for any shipping container associated with the shipment, important for managing cargo and logistics at scale.", "nullable": true }, "Carrier": { "type": "string", "description": "A unique identifier for the carrier associated with the shipping account. This code is typically alphanumeric and helps in identifying the specific carrier linked to the shipping account.", "nullable": true }, "DestinationCountryCode": { "type": "string", "description": "An abbreviation representing the destination country for the shipment, following the ISO 3166-1 alpha-2 standard, for example, \"GB\" for the United Kingdom.", "nullable": true }, "LastUpdatedBy": { "type": "string", "description": "The identifier (such as a username or system account) of the individual or system that last modified the shipment details, ensuring accountability.", "nullable": true }, "LastUpdatedDateUtc": { "type": "string", "description": "A timestamp indicating the last time the shipment details were updated, formatted in Coordinated Universal Time (UTC).", "format": "date-time" } }, "additionalProperties": false, "description": "Shipment Response" }, "ShipmentToTrackDetails": { "type": "object", "properties": { "TrackingNumber": { "type": "string", "description": "The tracking number assigned to the shipment by the carrier. This number is used to monitor the shipment's progress and location in transit.", "nullable": true, "example": "TT123456785GB" }, "CarrierCode": { "type": "string", "description": "A unique identifier for the carrier associated with the shipping account. This code is typically alphanumeric and helps in identifying the specific carrier linked to the shipping account.", "nullable": true, "example": "RM" }, "ShipmentId": { "type": "string", "description": "A unique identifier for each shipment. This ID is used to reference and track specific shipments within the system.", "format": "uuid", "example": "c4e60776-288f-464e-b35b-ff0f3252c0f0" } }, "additionalProperties": false, "description": "Tracking Number With Shipment Identifier" }, "ShipmentTrackingWebhookPushPayload": { "required": [ "CarrierCode", "Events", "ShipmentId", "TrackingNumber" ], "type": "object", "properties": { "TrackingNumber": { "minLength": 1, "type": "string", "description": "The tracking number assigned to the shipment by the carrier. This number is used to monitor the shipment's progress and location in transit." }, "ShipmentId": { "type": "string", "description": "A unique identifier for each shipment as returned from the **Create Shipment** or **Trackings** API endpoint. This ID is used to reference and track specific shipments within the system.", "format": "uuid" }, "ShipperReference": { "type": "string", "description": "The shipper's reference for this shipment. This is usually the shipper's order number that is provided to the receiver when the shipment was created.", "default": "" }, "CarrierCode": { "minLength": 1, "type": "string", "description": "A unique identifier for the carrier associated with the shipping account. This code is alphanumeric and helps in identifying the specific carrier." }, "Milestone": { "type": "string", "description": "A sequence of stages within the shipment process that are essential for monitoring progress, such as collected, label printed, out for delivery, and so on.\r
\r
This can be an empty string if no milestone corresponds to the tracking event, or it may indicate a significant event that has occurred during shipment, such as the following:\r
\r
• COLLECTED\r
• DELIVERED\r
• DELIVERY ATTEMPT FAILED\r
• IN CUSTOMS\r
• IN TRANSIT\r
• IT'S ON ITS WAY\r
• OUT FOR DELIVERY\r
• PART DELIVERED\r
• READY FOR COLLECTION\r
• TRANSIT DELAY\r
• UNDELIVERABLE", "default": "" }, "MilestoneDateTime": { "type": "string", "description": "The date and time at which the milestone event occurred. This is crucial for understanding the timeline of the shipment's journey.\r
\r
***Note**: The milestone date and time will be in the YYYY-MM-DD HH:MM:SS format.*", "default": "" }, "Events": { "type": "array", "items": { "$ref": "#/components/schemas/ShipmentTrackingWebhookPushPayloadEvent" }, "description": "An array of individual tracking events related to the shipment, providing detailed status updates and changes throughout the delivery process." } }, "additionalProperties": false, "description": "Shipment Tracking Webhook Push Payload\r
This is used in the following:\r
1. MCSS.Trackings to POST a dummy push payload when a user tests their customer webhook configuration from the website\r
2. MCSS.TrackingWebhook Sender to POST genuine tracking information to a customer's webhook\r
3. MCSS.Api to serve as the schema for a fake API endpoint documenting the shape of the push payload data, so that the customer can design their webhook" }, "ShipmentTrackingWebhookPushPayloadEvent": { "required": [ "EventDateTime", "EventDescription", "EventId", "EventLocation", "EventType" ], "type": "object", "properties": { "EventId": { "type": "string", "description": "A unique identifier for each specific event within the tracking events.", "format": "uuid" }, "EventType": { "minLength": 1, "type": "string", "description": "The type of event. This classification allows for quick identification of the shipment's status at any given time. The event type can be one of the following:\r
\r
• Delivery (if a final event)\r
• Milestone (if a tracking event that triggered a change of milestone)\r
• Tracking" }, "EventCode": { "$ref": "#/components/schemas/ShipmentTrackingWebhookPushPayloadEventCode" }, "EventDescription": { "minLength": 1, "type": "string", "description": "A detailed description of the event, providing context and specifics about what happened at this stage of the shipment's journey." }, "EventDateTime": { "minLength": 1, "type": "string", "description": "The date and time at which the event occurred, crucial for tracking the progress and timeline of the shipment.\r
\r
***Note**: The event date and time will be in the YYYY-MM-DD HH:MM:SS format.*" }, "EventUtcOffset": { "type": "string", "description": "The offset from Coordinated Universal Time (UTC) at which the event occurred. If provided by the carrier, this helps in converting event times to different time zones as needed.", "default": "" }, "EventLocation": { "$ref": "#/components/schemas/ShipmentTrackingWebhookPushPayloadEventLocation" } }, "additionalProperties": false, "description": "An array of individual tracking events related to the shipment, providing detailed status updates and changes throughout the delivery process." }, "ShipmentTrackingWebhookPushPayloadEventCode": { "enum": [ "BCUI", "BHBC", "BRBC", "CAAT", "CAFA", "CAFI", "CAFN", "CAFO", "CAFP", "CAMD", "CCAN", "CDNO", "CNAT", "COMM", "CSBK", "CSNO", "CSPI", "CSPN", "CSPO", "CSPP", "DDMG", "DELV", "DNSO", "DNSV", "DPAR", "DPOB", "DRCO", "DRFC", "DTNB", "DTNS", "DTSP", "EXPD", "FANK", "FCAR", "FDAF", "FINA", "FNCO", "FRAA", "FRNK", "FUDS", "FUTA", "ICAN", "IDAS", "IDES", "IDIP", "IARR", "ICLR", "IRCO", "IFME", "IMID", "INVD", "IOWS", "ISMI", "ISOH", "PINT", "POFD", "PPID", "PRET", "PRID", "PSAN", "PSCO", "PSCS", "PSDD", "PSDE", "PSDP", "PSRE", "RNCO", "RTNS", "RUND", "UDTS" ], "type": "string", "description": "A specific code assigned to the event, aiding in further classification of the event type." }, "ShipmentTrackingWebhookPushPayloadEventLocation": { "type": "object", "properties": { "Location": { "type": "string", "description": "The specific geographical location (for example, city or facility name) where the event was recorded, providing insight into logistics.", "default": "" }, "CountryCode": { "type": "string", "description": "An abbreviation representing the country where the event location is based, following the ISO 3166-1 alpha-2 standard, for example, \"GB\" for the United Kingdom. This is important for international tracking and logistical considerations.", "default": "" } }, "additionalProperties": false, "description": "The event location, indicating where the milestone or event took place." }, "ShipmentsPagedResponse": { "required": [ "Shipments", "TotalCount" ], "type": "object", "properties": { "Shipments": { "type": "array", "items": { "$ref": "#/components/schemas/ShipmentResponse" }, "description": "An array containing shipment objects for the requested page only. Each object includes detailed information about individual shipments." }, "TotalCount": { "type": "integer", "description": "An integer representing the total number of shipments that match the specified query criteria. This provides users with an overview of how many shipments are available on the system, enabling better understanding of the dataset.", "format": "int32", "example": 32 } }, "additionalProperties": false, "description": "The paged response containing the entities for the requested page only, and the total number available." }, "ShippingAccount": { "required": [ "AccountAlias", "AccountName", "AccountNumber", "AccountStatus", "AccountType", "CarrierCode", "ContactName", "ContactNumber", "LastUpdatedBy", "LastUpdatedDateUtc", "ShippingAccountId" ], "type": "object", "properties": { "ShippingAccountId": { "type": "string", "description": "A unique identifier for each shipping account assigned by the system **(ShippingAccountId)** or by you **(AccountAlias)**, allowing for efficient reference and management of individual accounts within the system.", "format": "uuid" }, "CarrierCode": { "minLength": 1, "type": "string", "description": "A unique identifier for the carrier associated with the shipping account. This code is typically alphanumeric and helps in identifying the specific carrier linked to the shipping account.", "example": "RM" }, "AccountNumber": { "minLength": 1, "type": "string", "description": "The number assigned to the shipping account by the carrier, typically used for tracking shipments and billing purposes.", "example": "0123456789" }, "AccountType": { "$ref": "#/components/schemas/AccountType" }, "AccountName": { "maxLength": 35, "minLength": 1, "type": "string", "description": "The official name of the shipping account as designated by the user or organisation, aiding in easy identification and reference of accounts.\r
\r
***Note:** By default, this value is set to the customer name.*", "example": "AB VideoGames" }, "AccountAlias": { "maxLength": 30, "minLength": 1, "type": "string", "description": "A unique, user-defined name for the shipping account, providing a convenient way to reference the account in a more memorable manner.", "example": "JSL" }, "AccountStatus": { "minLength": 1, "type": "string", "description": "The current status of the shipping account, which could denote whether it is active, inactive, or suspended, helping users understand the account's usability.", "example": "Enabled" }, "ContactName": { "maxLength": 100, "minLength": 1, "type": "string", "description": "The name of the primary contact person for the shipping account, facilitating communication regarding shipping and account-related matters.", "example": "John Smith" }, "ContactNumber": { "maxLength": 20, "minLength": 1, "type": "string", "description": "The phone number associated with the shipping account's primary contact person, facilitating communication regarding shipping inquiries, account management, and issue resolution.\r
\r
***Note**: Characters like +, /, -, or space are supported.*", "format": "tel", "example": "0123456789" }, "LastUpdatedBy": { "minLength": 1, "type": "string", "description": "The identifier (such as a username or system account) of the individual or system that last modified the shipping location information, ensuring accountability.", "example": "User A" }, "LastUpdatedDateUtc": { "type": "string", "description": "A timestamp indicating the last time the shipping account details were updated, formatted in Coordinated Universal Time (UTC).", "format": "date-time" } }, "additionalProperties": false, "description": "Shipping Account\r
An account that sends shipments. A shipping account is for a specified carrier.\r
You can have multiple shipping accounts.\r
A Shipping Account must have at least one Shipping Location." }, "ShippingAccountsPagedResponse": { "required": [ "ShippingAccounts", "TotalCount" ], "type": "object", "properties": { "ShippingAccounts": { "type": "array", "items": { "$ref": "#/components/schemas/ShippingAccount" }, "description": "An array containing all shipping accounts associated with the shipping location for the specific page only." }, "TotalCount": { "type": "integer", "description": "An integer representing the total number of shipping accounts associated with the specified shipping location, giving users a quick overview of how many accounts are linked to their operations.", "format": "int32", "example": 303 } }, "additionalProperties": false, "description": "The paged response containing the entities for the requested page only, and the total number available." }, "ShippingAccountsSortBy": { "enum": [ "Name", "Alias", "LastModified", "CarrierAccountNumber" ], "type": "string", "description": "Sort By" }, "ShippingLocation": { "required": [ "Address", "IsDefaultLocation", "LastUpdatedBy", "LastUpdatedDateUtc", "LocationAlias", "ShippingLocationId", "Timezone" ], "type": "object", "properties": { "ShippingLocationId": { "type": "string", "description": "A unique identifier assigned to the shipping location by the system (**shippingLocationId**). This ID is used to distinguish between different shipping locations within the system, facilitating, referencing and operations, such as updates, deletions, or specific queries related to that location.", "format": "uuid" }, "LocationAlias": { "maxLength": 100, "minLength": 1, "type": "string", "description": "A unique user-defined identifier for the shipping location, providing a convenient way to identify it, for example, Home or Warehouse.", "example": "Main Warehouse" }, "IsDefaultLocation": { "type": "boolean", "description": "A boolean value indicating whether the shipping location is set as the default for shipping operations, streamlining the selection process during shipments. \r
\r
If the location is set as the default one, the customers no longer need to specify the location for every shipment request, reducing the risk of errors and delays. It enhances consistency by ensuring that all shipments are directed to the same default location.\r
\r
***Note:** If true, then this location is set as the default one. Otherwise, it is set to false.*", "example": false }, "Timezone": { "maxLength": 100, "minLength": 1, "type": "string", "description": "The timezone in which the shipping location is located, important for scheduling and logistical considerations.", "example": "Europe/London" }, "LastUpdatedDateUtc": { "type": "string", "description": "A timestamp indicating the last time the shipping location details were updated, formatted in Coordinated Universal Time (UTC).", "format": "date-time", "example": "2022-02-06T16:13:24.010Z" }, "LastUpdatedBy": { "maxLength": 100, "minLength": 1, "type": "string", "description": "The identifier (such as a username or system account) of the individual or system that last modified the shipping location information, ensuring accountability.", "example": "User A" }, "Address": { "$ref": "#/components/schemas/ShippingLocationAddress" } }, "additionalProperties": false, "description": "Shipping Location\r
A location where the shipping account sends shipments from.\r
Every Shipping Account must have at least one Shipping Location.\r
A shipping account can have many shipping locations.\r
A shipping location can have many shipping accounts.\r
Each shipment created must be from an existing shipping location." }, "ShippingLocationAddress": { "type": "object", "properties": { "Line1": { "maxLength": 50, "type": "string", "description": "The first line of the address, typically containing the primary address information such as house number and street name.", "nullable": true, "example": "Brown Cottage" }, "Line2": { "maxLength": 50, "type": "string", "description": "An optional second line for the address, often used for additional details like apartment numbers or suite designations.", "nullable": true, "example": "Brown Cottage" }, "Line3": { "maxLength": 50, "type": "string", "description": "A third optional line in the address to include any further address specifications, allowing for more detailed address information if necessary.", "nullable": true }, "Town": { "maxLength": 50, "type": "string", "description": "The town or city, indicating the specific locality where the shipping location is situated.", "nullable": true, "example": "Christchurch" }, "Postcode": { "maxLength": 20, "type": "string", "description": "The postal or ZIP code corresponding to the shipping location, used for mail sorting and to identify specific geographic areas.", "nullable": true, "example": "TW20 0HJ" }, "County": { "maxLength": 50, "type": "string", "description": "The county, state, or province in which the shipping location resides, providing additional geographical context for the address.", "nullable": true, "example": "Surrey" }, "CountryCode": { "maxLength": 2, "minLength": 2, "type": "string", "description": "An abbreviation representing the country of the shipping location, following the ISO 3166-1 alpha-2 standard, for example, \"GB\" for the United Kingdom.", "nullable": true, "example": "GB" }, "What3Words": { "type": "string", "description": "A three-word location identifier provided by the What3words service, offering a precise way to define locations using a unique combination of three words, for example, the front door of 10 Downing Street in London is identified by slurs.this.shark.", "nullable": true, "example": "brick.space.employ" }, "ContactPhone": { "maxLength": 20, "type": "string", "description": "The contact phone number associated with the shipping location, facilitating communication regarding shipments or deliveries.", "format": "tel", "nullable": true, "example": "07123887422" } }, "additionalProperties": false, "description": "The complete address of the shipping location, consisting of multiple components including street information, locality, and so on." }, "ShippingLocationIdRequest": { "required": [ "ShippingLocationId" ], "type": "object", "properties": { "ShippingLocationId": { "maxLength": 100, "minLength": 1, "type": "string", "description": "A unique identifier assigned to the shipping location by the system (**shippingLocationId**) or by you (**LocationAlias**). This ID is used to distinguish between different shipping locations within the system, facilitating referencing and operations, such as updates, deletions, or specific queries related to that location.", "example": "D94E8CFD-604B-4B87-83E9-3F20CAF02837" } }, "additionalProperties": false, "description": "Shipping Location Id Request" }, "ShippingLocationRequest": { "required": [ "Address", "LocationAlias", "Timezone" ], "type": "object", "properties": { "LocationAlias": { "maxLength": 100, "minLength": 1, "type": "string", "description": "A unique user-defined identifier for the shipping location, providing a convenient way to identify it, for example, Home or Warehouse.", "example": "Main Warehouse" }, "Timezone": { "maxLength": 100, "minLength": 1, "type": "string", "description": "The timezone in which the shipping location is located, important for scheduling and logistical considerations.", "example": "Europe/London" }, "IsDefaultLocation": { "type": "boolean", "description": "A boolean value indicating whether the shipping location is set as the default for shipping operations, streamlining the selection process during shipments. \r
If the location is set as the default one, the customers no longer need to specify the location for every shipment request, reducing the risk of errors and delays. It enhances consistency by ensuring that all shipments are directed to the same default location.\r
\r
***Note:** If true, then this location is set as the default one. Otherwise, it is set to false.*", "nullable": true, "example": false }, "Address": { "$ref": "#/components/schemas/UpdateShippingLocationAddress" } }, "additionalProperties": false, "description": "Shipping Location Add / Update Request" }, "ShippingLocationsPagedResponse": { "required": [ "ShippingLocations", "TotalCount" ], "type": "object", "properties": { "ShippingLocations": { "type": "array", "items": { "$ref": "#/components/schemas/ShippingLocation" }, "description": "An array containing all shipping locations for the user account associated with the CarrierCode that was requested for the specific page only." }, "TotalCount": { "type": "integer", "description": "An integer representing the total number of shipping locations that match the specified query criteria. This provides users with an overview of how many shipping locations are available on the system, enabling better understanding of the dataset.", "format": "int32", "example": 303 } }, "additionalProperties": false, "description": "The paged response containing the entities for the requested page only, and the total number available." }, "ShippingLocationsSortBy": { "enum": [ "Name" ], "type": "string", "description": "Sort By" }, "Timezone": { "type": "object", "properties": { "TimezoneName": { "type": "string", "description": "The official name of the time zone. \r
This field is crucial for identifying time zones in the API response and can indicate the region or location it covers.", "nullable": true, "example": "Europe/Rome" }, "Country": { "type": "string", "description": "The name of the country associated with the time zone. \r
This field provides context regarding the geographical area in which the time zone is observed.", "nullable": true, "example": "Italy" }, "CountryCode": { "type": "string", "description": "A two-letter code (ISO 3166-1 alpha-2) that uniquely identifies the country associated with the time zone.\r
This code is useful for referencing countries in a standardised form", "nullable": true, "example": "IT" }, "UTCOffset": { "type": "string", "description": "The offset of the time zone from Coordinated Universal Time (UTC), expressed in hours and minutes. \r
This value indicates how far behind or ahead the time zone is from UTC, which is essential for time calculations.", "nullable": true, "example": "UTC+1" } }, "additionalProperties": false, "description": "Time zone\r
A location can have multiple time zones.\r
A location must have at least one time zone." }, "TimezonesPagedResponse": { "required": [ "TimeZones", "TotalCount" ], "type": "object", "properties": { "TimeZones": { "type": "array", "items": { "$ref": "#/components/schemas/Timezone" }, "description": "An array containing the individual time zone records retrieved by the API. \r
Each record provides specific information about a particular time zone." }, "TotalCount": { "type": "integer", "description": "An integer representing the total number of time zones matching the search criteria, regardless of pagination. \r
This information is useful for understanding the full scope of available results.", "format": "int32", "example": 1 } }, "additionalProperties": false, "description": "The paged response containing the entities for the requested page only, and the total number available." }, "TimezonesSortBy": { "enum": [ "TimezoneName", "Country", "CountryCode" ], "type": "string", "description": "Sort By" }, "UpdateAddressBook": { "required": [ "CountryCode", "Line1", "Town" ], "type": "object", "properties": { "ContactName": { "maxLength": 50, "type": "string", "description": "The name of the primary contact associated with the address. This field is essential for identification and communication purposes.", "nullable": true, "example": "Jane Doe" }, "CompanyName": { "maxLength": 50, "type": "string", "description": "The name of the company linked to the address. This field provides context for the address, especially in business-related queries.", "nullable": true, "example": "My Company Ltd." }, "ContactEmail": { "maxLength": 254, "type": "string", "description": "The email address of the primary contact for the address. This is used for correspondence and can facilitate communication directly related to the address.", "format": "email", "nullable": true, "example": "jane@example.com" }, "ContactPhone": { "maxLength": 20, "type": "string", "description": "The phone number of the primary contact associated with the address. This field is crucial for any immediate communication needs.", "format": "tel", "nullable": true }, "Line1": { "maxLength": 50, "minLength": 1, "type": "string", "description": "The first line of the address, typically containing the primary address information such as house number and street name.", "example": "10 Sky Lane" }, "Line2": { "maxLength": 50, "type": "string", "description": "An optional second line for the address, often used for additional details like apartment numbers or suite designations.", "nullable": true }, "Line3": { "maxLength": 50, "type": "string", "description": "A third optional line in the address to include any further address specifications, allowing for more detailed address information if necessary.", "nullable": true }, "Town": { "maxLength": 50, "minLength": 1, "type": "string", "description": "The town or city, indicating the specific locality where the address is located." }, "Postcode": { "maxLength": 20, "type": "string", "description": "The postal or ZIP code corresponding to the address, used to identify specific geographic areas.", "nullable": true }, "County": { "maxLength": 50, "type": "string", "description": "The county, state, or province in which the address is located, providing additional geographical context for the address.", "nullable": true }, "CountryCode": { "maxLength": 2, "minLength": 2, "type": "string", "description": "An abbreviation representing the country of the address, following the ISO 3166-1 alpha-2 standard, for example, \"GB\" for the United Kingdom.", "example": "GB" }, "What3Words": { "type": "string", "description": "A three-word location identifier provided by the What3words service, offering a precise way to define addresses using a unique combination of three words, for example, the front door of 10 Downing Street in London is identified by slurs.this.shark.", "nullable": true, "example": "brick.space.employ" } }, "additionalProperties": false, "description": "Update AddAddressBook Request" }, "UpdateContainerRequest": { "required": [ "ShipmentIds" ], "type": "object", "properties": { "ShipmentIds": { "type": "array", "items": { "type": "string" }, "description": "An array of unique identifiers for the shipments being added to or removed from the container. These IDs can be the shipment Id or tracking/barcode numbers. For consignment shipments, only consignment-level tracking/barcode numbers are permitted.\r
\r
***Note:** The maximum number of shipments that can be included in a single request is 10,000, allowing for bulk management of container contents.*" }, "Mode": { "$ref": "#/components/schemas/UpdateMode" } }, "additionalProperties": false, "description": "Update Container Request" }, "UpdateMode": { "enum": [ "Add", "Remove" ], "type": "string", "description": "A string specifying the mode of operation for the update. This field indicates how the shipment should be processed, such as whether to add new shipments or remove the existing ones, providing users with flexibility in managing their container effectively.\r
\r
If the mode is Add, the system validates whether the shipment(s) being added to the container belong to the same shipping account as the container. If any shipment does not belong to the same shipping account as the container, an error is returned in the response.\r
\r
***Note:** By default, this field is set to Add.*" }, "UpdateShippingLocationAddress": { "type": "object", "properties": { "Line1": { "maxLength": 50, "type": "string", "description": "The first line of the address, typically containing the primary address information such as house number and street name. \r
A maximum of 50 characters is permitted. However, it may vary depending on the carrier selection.\r
\r
***Note:** This information is only required if the address is not used from the stored addresses in the **Address Book**.*", "nullable": true, "example": "Brown Cottage" }, "Line2": { "maxLength": 50, "type": "string", "description": "An optional second line for the address, often used for additional details like apartment numbers or suite designations.\r
A maximum of 50 characters is permitted. However, it may vary depending on the carrier selection.", "nullable": true, "example": "10 Sky Lane" }, "Line3": { "maxLength": 50, "type": "string", "description": "A third optional line in the address to include any further address specifications, allowing for more detailed address information if necessary.\r
A maximum of 50 characters is permitted. However, it may vary depending on the carrier selection.", "nullable": true, "example": "Hills End" }, "Town": { "maxLength": 50, "type": "string", "description": "The town or city, indicating the specific locality where the shipping location is situated.\r
A maximum of 50 characters is permitted. However, it may vary depending on the carrier selection.\r
\r
***Note:** This information is only required if the address is not used from the stored addresses in the Address Book.*", "nullable": true, "example": "Christchurch" }, "Postcode": { "maxLength": 20, "type": "string", "description": "The postal or ZIP code corresponding to the shipping location, used for mail sorting and to identify specific geographic areas.\r
A maximum of 50 characters is permitted. However, it may vary depending on the carrier selection. \r
\r
***Note:** This information is only required for the addresses in the UK and for some outside it. To check for the postcode requirements, refer to the **Countries** API.*", "nullable": true, "example": "TW20 0HJ" }, "County": { "maxLength": 50, "type": "string", "description": "The county, state, or province in which the shipping location resides, providing additional geographical context for the address.\r
A maximum of 50 characters is permitted. However, it may vary depending on the carrier selection.\r
\r
***Note:** This information may be required depending on the country. If the country is USA, Australia, or Canada, then it must be a valid state code or name. To check for the county/state/province requirements, refer to the **Countries** API.*", "nullable": true, "example": "Surrey" }, "CountryCode": { "maxLength": 2, "minLength": 2, "type": "string", "description": "An abbreviation representing the country of the shipping location, following the ISO 3166-1 alpha-2 standard, for example, \"GB\" for the United Kingdom.\r
\r
***Note**: This information is only required if the address is not used from the stored addresses in the **Address Book***", "nullable": true, "example": "GB" }, "What3Words": { "type": "string", "description": "A three-word location identifier provided by the What3words service, offering a precise way to define locations using a unique combination of three words, for example, the front door of 10 Downing Street in London is identified by slurs.this.shark.", "nullable": true, "example": "brick.space.employ" }, "ContactPhone": { "maxLength": 20, "type": "string", "description": "The contact phone number associated with the shipping location, facilitating communication regarding shipments or deliveries.\r
\r
***Note:** If the shipper address is not provided for the **Create Shipment** request, this information is used as the shipper's contact phone number, if provided. Characters like +, /, -, or space are supported.*", "format": "tel", "nullable": true, "example": "07123887422" } }, "additionalProperties": false, "description": "The complete address of the shipping location, consisting of multiple components including street information, locality, and so on." }, "UpdateStatusRequest": { "required": [ "ShipmentIds", "Status" ], "type": "object", "properties": { "Status": { "$ref": "#/components/schemas/UpdateStatusType" }, "Reason": { "type": "string", "description": "A string providing the reason for the status update. Depending on the shipment's current status, specify why a shipment's status is being changed, adding context and aiding in future audits and management.\r
\r
If the status you are updating to is **Hold**, then you must provide the reason using one of the following values:\r
• Awaiting Dispatch\r
• Awaiting Payment\r
• Awaiting Stock\r
• Awaiting Customer Response\r
• Held for Shipping Day\r
• Weight Consolidation\r
• Warehouse Processing\r
\r
If the status you are updating to is **Cancel**, then you must provide the reason using one of the following values:\r
• Order Cancelled\r
• Packed in Error\r
• Repacked", "nullable": true }, "ShipmentIds": { "type": "array", "items": { "type": "string" }, "description": "An array of unique identifiers for the shipments that are being updated. This field specifies to which shipments the new status will apply, allowing for batch processing of multiple shipments in a single request.\r
\r
***Note**: There must be at least one shipment and a maximum of 99. This value can be an ID or a tracking/barcode number. However, for consignment shipments, only the consignment-level tracking/barcode number can be used.*" } }, "additionalProperties": false, "description": "Update Status Request" }, "UpdateStatusType": { "enum": [ "Hold", "Cancel", "Release", "Picked" ], "type": "string", "description": "A field indicating one of the following statuses to assign to the specified shipments.\r
" }, "WeightUnitOfMeasure": { "enum": [ "KG", "Grams" ], "type": "string", "description": "The unit of measurement for the weight provided, such as **TotalWeight**, indicating whether the weight is specified in kilograms (KG) or grams (G), ensuring clarity for shipping calculations.\r
\r
***Note**: By default, this field is set to KG.*" } }, "securitySchemes": { "oauth2": { "type": "oauth2", "description": "JSON Web Token (JWT) authorization header using the Bearer scheme.\r\n\r\nExample: \"bearer { token }\"", "flows": { "clientCredentials": { "tokenUrl": "https://authentication.proshipping.net/connect/token", "scopes": { } } } } } }, "security": [ { "oauth2": [ ] } ], "tags": [ { "name": "Carriers", "description": "This section provides all the information relating to carriers available on the system." }, { "name": "Shipping Locations", "description": "This section provides information relating to managing shipping locations.\n\nA shipping location is an address from where the items are being despatched." }, { "name": "Shipping Accounts", "description": "This section provides information relating to managing shipping accounts.\n\nA shipping account is where you assign your carrier credentials and link them to the relevant shipping location/s." }, { "name": "Shipments", "description": "This section provides information relating to creating shipments, printing shipping labels and customs documentation." }, { "name": "PUDO Locations", "description": "PUDO (Pick Up Drop Off) allows a location to be specified for the recipient to pick up/collect a shipment from (in the case of an outbound shipment) or the sender to drop the shipment off to (in the case of a return shipment). The PUDO location is likely to be a Post Office, local shop, retail outlet etc." }, { "name": "Manifests", "description": "This section provides information relating to manifesting shipments for the end of day process." }, { "name": "Containers", "description": "A container is a way of grouping specific shipments together ready for manifesting.\n\nThis section provides information relating to creating and managing containers and their associated shipments prior to manifesting\n\nNote: It is not mandatory to develop the Container API, however this feature might help if you need to manifest certain groups of shipments separate from the rest of the shipments you produced that day i.e. you might want to create a container for Royal Mail's collection at 2PM, and then have a separate container for collection at 3PM. By placing all the individual shipments into a container this allows you to manifest unlimited numbers of shipments." }, { "name": "Products", "description": "This section provides information relating to managing products." }, { "name": "Address Book", "description": "This section provides information related to managing your shipping addresses." }, { "name": "Reference Data", "description": "This section provides information about reference data used on the system." } ], "x-readme": { "explorer-enabled": false } }