About specifying payors

The Shipium system supports billing multiple payor accounts separately for costs associated with a shipment for carriers including DHL, FedEx, Midland, Purolator E-Ship, UPS, and USPS. Different carriers support different payor types and require varying data for each payor type. This document provides guidance for the most common carriers used by Shipium customers. Details on payor account credential information are included in the request fields table below, and carrier-specific information follows.

Specify payor details in calls to Shipium's APIs

If your organization needs to specify multiple payors using different billing account information in calls to Shipium's APIs, you can include the payorAccounts object in the shipmentParameters or multiParcelShipmentParameters of your call. Requirements differ by carrier and are included in the carrier sections that follow: DHL, FedEx, Midland, OnTrac, Purolator E-Ship, UPS, and USPS.

👉
Account information included via API call in payorAccounts will override account credentials configured in the Shipium Console.

You should include one payorAccounts entry for each unique payor account and carrier across which you want to split shipping costs and/or duties and taxes.

Payor request details

The following table lists all required and optional fields for payor accounts. Conditional fields dependent upon carrier requirements are explained further in the carrier-specific guidance that follows. The request fields listed here relate to payor accounts only; other request fields are described in API-specific documentation.

Request field	Required/Optional	Field properties	Description
`payorAccounts`	Required	An array of payor account information, representing the list of payor accounts associated with the shipment	Each account corresponds to a specific carrier and is used to determine the entity responsible for shipping charges when billing terms require a designated payor. If a selected carrier does not have a corresponding payor account in this list, standard billing configurations will apply.
`payorAccounts.accountType`	Required	String enumeration Values are: `collect` `consignee` `recipient` `sender` `third_party`	The type of account to use for billing
`payorAccounts.carrierId`	Conditional Required for `third_party` and `collect` account types. Optional for `sender`, `recipient`, and `consignee` account types	String enumeration Ex.: `ups`	The carrier ID as represented in the Shipium platform; you can find carrier ID values in Supported Carriers.
`payorAccounts .payorAccountCredentials .accountNumber`	Conditional, dependent upon carrier	String	Your organization's carrier account number used to authenticate and connect to the carrier's APIs
`payorAccounts .payorAccountCredentials .accountCountryCode`	Conditional, dependent upon carrier	String	The ISO 3166-1 country code associated with your organization's carrier account
`payorAccounts .payorAccountCredentials .accountPostalCode`	Conditional, dependent upon carrier	String	A country-code-appropriate postal code associated with your organization's carrier account
`payorAccounts .payorAccountAddress`	Conditional	Structure	The payor account address information. Note that this is required for some carriers like Midland for `third_party` `accountType`.
`payorAccounts .payorAccountAddress.name`	Optional	String	The name of the shipment payor
`payorAccounts .payorAccountAddress .phoneNumber`	Optional	String	The phone number of the shipment payor
`payorAccounts .payorAccountAddress .phoneNumberCountryCode`	Optional	String	The phone number country code of the shipment payor
`payorAccounts .payorAccountAddress .emailAddress`	Optional	String	The email address of the shipment payor
`payorAccounts .payorAccountAddress .company`	Optional	String	The company associated with the shipment payor
`payorAccounts .payorAccountAddress .street1`	Optional	String	The first address line for the shipment payor
`payorAccounts .payorAccountAddress .street2`	Optional	String	The second address line for the shipment payor
`payorAccounts .payorAccountAddress.city`	Optional	String	The city of the address for the shipment payor
`payorAccounts .payorAccountAddress.state`	Optional	String	The two-letter postal abbreviation of the state for the shipment payor's address
`payorAccounts .payorAccountAddress .countryCode`	Conditional, dependent upon carrier	String	The ISO 3166-1 country code for the shipment payor's address
`payorAccounts .payorAccountAddress .postalCode`	Conditional, dependent upon carrier	String	A country-code-appropriate postal code for the shipment payor's address
`payorAccounts .payorAccountAddress .addressType`	Optional	String enumeration Values are: `commercial` `residential`	The type of location for the shipment payor's address
`payorAccounts .payorAccountAddress .addressLineComponents`	Optional, but preferred for Mexican addresses	An array of address line components	The address line components for the payor account address, used for some international shipments; this optional address object is not included in the example JSON request. You can find out more about Mexican addresses in Non-U.S. Address Formats .
`payorAccounts .registrationInformation .typeCode`	Optional	String enumeration Values are: `EIN` (Employee Identification Number) `EOR` (Economic Operators Registration and Identification) `GST` (Goods and Services Tax) `VAT` (Value Added Tax)	The registration number type code for the payor account
`payorAccounts .registrationInformation .registrationNumber`	Conditional (required for the `consignee` account type; optional for other account types)	String Ex.: `12344509`	The registration number for the payor account
`payorAccounts .registrationInformation .issuerCountryCode`	Optional	String	The ISO 3166-1 country code for payor account
`payorAccounts .billForShippingCost`	Required	Boolean `true` or `false`	If `true`, this indicates whether the payor should be billed for the cost of shipping the package; the value should be `false` when designating tax ID (`EIN`) for a payor type (`typeCode`).
`payorAccounts .billDutiesAndTaxes`	Required	Boolean `true` or `false`	If `true`, this indicates whether the payor should be billed for duties and taxes; the value should be `false` when designating tax ID (`EIN`) for a payor type (`typeCode`).

Carrier-specific information for payors

DHL payor information

Payor type	DHL supports payor type	DHL requires payor account credentials
`sender`	Yes	Yes
`third_party`	Yes	Yes
`consignee`	Yes	Yes
`recipient`	Yes	Yes

DHL required fields

The following fields must be included for DHL for any of the supported payor types: sender, third party, consignee, or recipient.

Request field	Field properties	Description
`payorAccounts.accountType`	String enumeration Values are: `consignee` `recipient` `sender` `third_party`	The type of account to use for billing
`payorAccounts.carrierId`	Conditional: Required for`third_party` account type String enumeration Ex.: `dhl`	The carrier ID as represented in the Shipium platform; you can find carrier ID values in Supported Carriers.
`payorAccounts .payorAccountCredentials .accountNumber`	String	Your organization's carrier account number used to authenticate and connect to the carrier's APIs
`payorAccounts.payorAccountAddress .name`	String	The name of the shipment payor
`payorAccounts.payorAccountAddress .company`	String	The company associated with the shipment payor
`payorAccounts.payorAccountAddress .phoneNumber`	String	The phone number of the shipment payor
`payorAccounts.payorAccountAddress .street1`	String	The first address line for the shipment payor
`payorAccounts.payorAccountAddress .street2`	String	The second address line for the shipment payor
`payorAccounts.payorAccountAddress .city`	String	The city of the address for the shipment payor
`payorAccounts.payorAccountAddress .postalCode`	String	A country-code-appropriate postal code for the shipment payor's address
`payorAccounts.payorAccountAddress .countryCode`	String	The ISO 3166-1 country code for the shipment payor's address
`payorAccounts .registrationInformation .registrationNumber`	String Ex.: `12344509`	The registration number for the payor account; this is required for the `consignee` account type but optional for other account types.
`payorAccounts.billForShippingCost`	Boolean `true` or `false`	If `true`, this indicates whether the payor should be billed for the cost of shipping the package; the value should be `false` when designating tax ID (`EIN`) for a payor type (`typeCode`).
`payorAccounts.billDutiesAndTaxes`	Boolean `true` or `false`	If `true`, this indicates whether the payor should be billed for duties and taxes; the value should be `false` when designating tax ID (`EIN`) for a payor type (`typeCode`).

Sample request for consignee billing for DHL

This example shows the required payorAccounts information in JSON to be included via API call for consignee billing for DHL.

{
  ....
  "shipmentParameters": {
    "payorAccounts": [
      {
        "accountType": "consignee",
        "payorAccountCredentials": {
          "accountNumber": "123456789"
        },
  "payorAccountAddress": {
          "name": "Wile E. Coyote",
          "company": "ACME",
          "phoneNumber": "888-555-1234",
          "street1": "123 Main St.",
          "street2": "Suite 42",
          "city": "Albuquerque",
          "postalCode": "87121",
          "countryCode": "US"
  },
"registrationInformation": {
  "registrationNumber": "12344509"
},
        "billForShippingCost": false,
        "billDutiesAndTaxes": false
      }
    ]
  },
  ....
}

FedEx payor information

Payor type	FedEx supports payor type	FedEx requires payor account credentials
`sender`	Yes	Yes
`third_party`	Yes	Yes
`consignee`	No	Not Applicable
`collect`	Yes ✳️	Yes
`recipient`	Yes	Yes

✳️ FedEx supports collect on delivery billing to a consignee for intra-Canada shipments via its FedEx Ground service method.

FedEx required fields

The following fields must be included for FedEx for any of the supported payor types: sender, third party, or recipient.

Request field	Field properties	Description
`payorAccounts.accountType`	String enumeration Values are: `recipient` `sender` `third_party` `collect`	The type of account to use for billing
`payorAccounts.carrierId`	Conditional: Required for`third_party` and `collect` account types String enumeration Ex.: `fedex`	The carrier ID as represented in the Shipium platform; you can find carrier ID values in Supported Carriers.
`payorAccounts .payorAccountCredentials .accountNumber`	String	Your organization's carrier account number used to authenticate and connect to the carrier's APIs
`payorAccounts .payorAccountCredentials .accountCountryCode`	String	The ISO 3166-1 country code associated with your organization's carrier account
`payorAccounts.payorAccountAddress .phoneNumber`	String	The phone number of the shipment payor
`payorAccounts.payorAccountAddress .street1`	String	The first address line for the shipment payor
`payorAccounts.payorAccountAddress .street2`	String	The second address line for the shipment payor
`payorAccounts.payorAccountAddress .city`	String	The city of the address for the shipment payor
`payorAccounts.payorAccountAddress .countryCode`	String	The ISO 3166-1 country code for the shipment payor's address
`payorAccounts.billForShippingCost`	Boolean `true` or `false`	If `true`, this indicates whether the payor should be billed for the cost of shipping the package.
`payorAccounts.billDutiesAndTaxes`	Boolean `true` or `false`	If `true`, this indicates whether the payor should be billed for duties and taxes.

Sample request for recipient billing for FedEx

This example shows the required payorAccounts information in JSON to be included via API call for recipient billing for FedEx.

{
  ....
  "shipmentParameters": {
    "payorAccounts": [
      {
        "accountType": "recipient",
        "carrierId": "fedex",
        "payorAccountCredentials": {
          "accountNumber": "123456789",
          "accountCountryCode": "US"
        },
        "payorAccountAddress": {
          "phoneNumber": "8312776565",
          "street1": "123 Main St.",
          "street2": "Suite 42",
          "city": "Albuquerque",
          "countryCode": "US"
        },
        "billForShippingCost": true,
        "billDutiesAndTaxes": true
      }
    ]
  },
  ....
}

Midland payor information

Payor type	Midland supports payor type	Midland requires payor account credentials
`sender`	Yes	No
`third_party`	Yes	Yes ✳️
`consignee`	No	Not Applicable
`recipient`	No	Not Applicable
`collect`	Yes	Yes

✳️ Midland does not require an account number for third party billing but does require third party address and contact information.

Midland required fields

The following fields must be included for Midland, depending on the supported payor type: sender or third party.

Request field	Required/Optional	Field properties	Description
`payorAccounts.accountType`	Required for all payor types	String enumeration Values are: `sender` `third_party` `collect`	The type of account to use for billing
`payorAccounts.carrierId`	Required for `third_party` and `collect` payor types	String enumeration Ex.: `fedex`	The carrier ID as represented in the Shipium platform; you can find carrier ID values in Supported Carriers .
`payorAccounts .payorAccountCredentials .accountCountryCode`	Required for `third_party` payor type; not required for `sender`	String	The ISO 3166-1 country code associated with your organization's carrier account
`payorAccounts .payorAccountCredentials .accountPostalCode`	Required for `third_party` payor type; not required for `sender`	String	A country-code-appropriate postal code associated with your organization's carrier account
`payorAccounts.payorAccountAddress .name`	Required for `third_party` payor type; not required for `sender`	String	The name of the shipment payor
`payorAccounts.payorAccountAddress .phoneNumber`	Required for `third_party` payor type; not required for `sender`	String	The phone number of the shipment payor
`payorAccounts.payorAccountAddress .phoneNumberCountryCode`	Required for `third_party` payor type; not required for `sender`	String	The phone number country code of the shipment payor
`payorAccounts.payorAccountAddress .emailAddress`	Required for `third_party` payor type; not required for `sender`	String	The email address of the shipment payor
`payorAccounts.payorAccountAddress .company`	Required for `third_party` payor type; not required for `sender`	String	The company associated with the shipment payor
`payorAccounts.payorAccountAddress .street1`	Required for `third_party` payor type; not required for `sender`	String	The first address line for the shipment payor
`payorAccounts.payorAccountAddress .street2`	Required for `third_party` payor type; not required for `sender`	String	The second address line for the shipment payor
`payorAccounts.payorAccountAddress .city`	Required for `third_party` payor type; not required for `sender`	String	The city of the address for the shipment payor
`payorAccounts.payorAccountAddress .state`	Required for `third_party` payor type; not required for `sender`	String	The two-letter postal abbreviation of the state for the shipment payor's address
`payorAccounts.payorAccountAddress .countryCode`	Required for `third_party` payor type; not required for `sender`	String	The ISO 3166-1 country code for the shipment payor's address
`payorAccounts.payorAccountAddress .postalCode`	Required for `third_party` payor type; not required for `sender`	String	A country-code-appropriate postal code for the shipment payor's address
`payorAccounts.billForShippingCost`	Required for all payor types	Boolean `true` or `false`	If `true`, this indicates whether the payor should be billed for the cost of shipping the package.
`payorAccounts.billDutiesAndTaxes`	Required for all payor types	Boolean `true` or `false`	If `true`, this indicates whether the payor should be billed for duties and taxes.

Sample request for sender billing for Midland

This example shows the required payorAccounts information in JSON to be included via API call for sender billing for Midland.

{
    "shipmentParameters": {
        "payorAccounts": [
            {
                "accountType": "sender",
                "billForShippingCost": true,
                "billDutiesAndTaxes": true
            }
        ]
    }
}

OnTrac payor information

Payor type	OnTrac supports payor type	OnTrac requires payor account credentials
`sender`	Yes	Yes
`third_party`	Yes	Yes
`consignee`	Yes	Yes
`recipient`	Yes	Yes

OnTrac required fields

The following fields must be included for OnTrac for any of the supported payor types: sender, third party, consignee, or recipient.

Request field	Field properties	Description
`payorAccounts.accountType`	String enumeration Values are: `consignee` `recipient` `sender` `third_party`	The type of account to use for billing
`payorAccounts.carrierId`	Conditional: Required for`third_party` account type String enumeration Ex.: `ontrac`	The carrier ID as represented in the Shipium platform; you can find carrier ID values in Supported Carriers.
`payorAccounts .payorAccountCredentials .accountNumber`	String	Your organization's carrier account number used to authenticate and connect to the carrier's APIs
`payorAccounts.billForShippingCost`	Boolean `true` or `false`	If `true`, this indicates whether the payor should be billed for the cost of shipping the package.
`payorAccounts.billDutiesAndTaxes`	Boolean `true` or `false`	If `true`, this indicates whether the payor should be billed for duties and taxes.

Sample request for third party billing for OnTrac

This example shows the required payorAccounts information in JSON to be included via API call for third party billing for OnTrac.

{
  ....
  "shipmentParameters": {
    "payorAccounts": [
     {
         "accountType": "third_party",
         "carrierId": "ontrac",
         "payorAccountCredentials": {
             "accountNumber": "123456789"
         },
         "billForShippingCost": true,
         "billDutiesAndTaxes": true
     }
    ]
  },
  ....
}

Purolator E-Ship payor information

Payor type	Purolator E-Ship supports payor type	Purolator E-Ship requires payor account credentials
`sender`	Yes	Yes
`third_party`	Yes	Yes
`consignee`	No	Not Applicable
`recipient`	Yes	Yes

Purolator E-Ship required fields

The following fields must be included for Purolator E-Ship for any of the supported payor types: sender, third party, consignee, or recipient.

Request field	Field properties	Description
`payorAccounts.accountType`	String enumeration Values are: `recipient` `sender` `third_party`	The type of account to use for billing
`payorAccounts.carrierId`	Conditional: Required for`third_party` account type String enumeration Ex.: `purolator`	The carrier ID as represented in the Shipium platform; you can find carrier ID values in Supported Carriers.
`payorAccounts .payorAccountCredentials .accountNumber`	String	Your organization's carrier account number used to authenticate and connect to the carrier's APIs
`payorAccounts .billForShippingCost`	Boolean `true` or `false`	If `true`, this indicates whether the payor should be billed for the cost of shipping the package.
`payorAccounts .billDutiesAndTaxes`	Boolean `true` or `false`	If `true`, this indicates whether the payor should be billed for duties and taxes.

Sample request for third party billing for Purolator E-Ship

This example shows the payorAccounts information in JSON to be included via API call for third party billing for Purolator E-Ship.

{
  ....
  "shipmentParameters": {
    "payorAccounts": [
      {
        "accountType": "third_party",
        "carrierId": "purolator",
        "payorAccountCredentials": {
          "accountNumber": "123456789"
        },
        "billForShippingCost": true,
        "billDutiesAndTaxes": true
      }
    ]
  },
  ....
}

UPS payor information

Payor type	UPS supports payor type	UPS requires payor account credentials
`sender`	Yes	Yes
`third_party`	Yes	Yes
`consignee`	Yes	Yes
`recipient`	Yes	Yes

UPS required fields

The following fields must be included for UPS for any of the supported payor types: sender, third party, consignee, or recipient.

Request field	Required/Optional	Field properties	Description
`payorAccounts.accountType`	Required for all payor types	String enumeration Values are: `consignee` `recipient` `sender` `third_party`	The type of account to use for billing
`payorAccounts.carrierId`	Required for `third_party` account type	String enumeration Ex.: `ups`	The carrier ID as represented in the Shipium platform; you can find carrier ID values in Supported Carriers.
`payorAccounts .payorAccountCredentials .accountNumber`	Required for `sender`, `recipient`, and `third_party` payor types; not required for `consignee`	String	Your organization's carrier account number used to authenticate and connect to the carrier's APIs
`payorAccounts .payorAccountCredentials .accountCountryCode`	Required for `third_party` payor type; not required for `consignee`, `sender`, or `recipient`	String	The ISO 3166-1 country code associated with your organization's carrier account
`payorAccounts .payorAccountCredentials .accountPostalCode`	Required for `recipient` and `third_party` payor types; not required for `consignee` or `sender`	String	A country-code-appropriate postal code associated with your organization's carrier account
`payorAccounts .payorAccountAddress .countryCode`	Required for `third_party` payor type; not required for `consignee`, `sender`, or `recipient`	String	The ISO 3166-1 country code for the shipment payor's address
`payorAccounts .payorAccountAddress .postalCode`	Required for `recipient` and `third_party` payor types; not required for `consignee` or `sender`	String	A country-code-appropriate postal code for the shipment payor's address
`payorAccounts .registrationInformation .registrationNumber`	Required for `consignee` payor type; not required for `recipient`, `sender`, or `third_party`	String Ex.: `12344509`	The registration number for the payor account
`payorAccounts .billForShippingCost`	Required for all payor types	Boolean `true` or `false`	If `true`, this indicates whether the payor should be billed for the cost of shipping the package; the value should be `false` when designating tax ID (`EIN`) for a payor type (`typeCode`).
`payorAccounts .billDutiesAndTaxes`	Required for all payor types	Boolean `true` or `false`	If `true`, this indicates whether the payor should be billed for duties and taxes; the value should be `false` when designating tax ID (`EIN`) for a payor type (`typeCode`).

Sample request for recipient billing for UPS

This example shows the payorAccounts information in JSON to be included via API call for billing for a recipient for UPS.

{
  ....
  "shipmentParameters": {
    "payorAccounts": [
      {
        "accountType": "recipient",
        "payorAccountCredentials": {
          "accountNumber": "123456789",
          "accountPostalCode": "98101"
        },
        "payorAccountAddress": {
          "postalCode": "87121"
        },
        "billForShippingCost": true,
        "billDutiesAndTaxes": true
      }
    ]
  },
  ....
}

Sample request for consignee billing for UPS

This example shows the required payorAccounts information as well as optional fields in JSON to be included via API call for billing for a consignee for UPS.

{
    "currencyCode": "usd",
    "generateLabel": false,
    "shipmentParameters": {
        "includePackagesArray": true,
        "shippedDateTime": "2023-09-06T18:30:55.558Z",
        "orderedDateTime": "2022-04-07T18:30:55.558Z",
        "testMode": true,
        "destinationAddress": {
            "countryCode": "US",
            "postalCode": "87121",
            "addressType": "commercial",
            "city": "Albuquerque",
            "name": "Wile E. Coyote",
            "phoneNumber": "888-555-1234",
            "state": "NM",
            "street1": "123 Main St.",
            "street2": "Suite 42"
        },
        "shipFromAddress": {
            "countryCode": "US",
            "postalCode": "17901",
            "city": "Pottsville",
            "state": "PA",
            "street1": "401 N. Centre St."
        },
        "returnToAddress": {
            "name": "Rod Runner",
            "phoneNumber": "865-433-9999",
            "phoneNumberCountryCode": "+2",
            "emailAddress": "[email protected]",
            "company": "ACME",
            "street1": "456 Main St.",
            "street2": "Suite 8",
            "city": "Albuquerque",
            "state": "NM",
            "countryCode": "US",
            "postalCode": "87121",
            "addressType": "commercial"
        },
        "payorAccounts": [
            {
                "accountType": "consignee",
                "payorAccountCredentials": {
                  "accountNumber": "123456789",
                  "accountPostalCode": "98101"
                },
              "registrationInformation": {
                "registrationNumber": "12344509"
              },
                "billForShippingCost": false,
                "billDutiesAndTaxes": false
            }
        ],
        "orderItemQuantities": [
            {
                "productId": "ET-14-4000",
                "quantity": 2
            }
        ],
        "packagingType": {
            "packagingMaterial": "box",
            "packagingWeight": {
                "weight": 13,
                "weightUnit": "oz"
            },
            "linearDimensions": {
                "length": 15,
                "width": 10,
                "height": 5,
                "linearUnit": "in"
            }
        },
        "totalWeight": {
            "weight": 13,
            "weightUnit": "oz"
        }
    }
}

Sample response for consignee billing for UPS

"shipiumShipmentId": "3185ae04-d465-408a-9ae2-a98c7499e6bc",
    "orderedDateTime": "2022-04-07T18:30:55.558Z",
    "shippedDateTime": "2023-09-06T18:30:55.558Z",
    "ignoreUpgradeSpendLimits": false,
    "fulfillmentType": "customer",
    "packages": [
        {
            "orderItemQuantities": [
                {
                    "productId": "ET-14-4000",
                    "quantity": 2,
                    "productDetails": [],
                    "hazmat": false
                }
            ],
            "packagingType": {
                "packagingMaterial": "box",
                "linearDimensions": {
                    "linearUnit": "in",
                    "length": 15.0,
                    "width": 10.0,
                    "height": 5.0
                },
                "packagingWeight": {
                    "weightUnit": "oz",
                    "weight": 13.0
                }
            },
            "totalWeight": {
                "weightUnit": "oz",
                "weight": 13.0
            }
        }
    ],
    "orderItemQuantities": [
        {
            "productId": "ET-14-4000",
            "quantity": 2,
            "productDetails": [],
            "hazmat": false
        }
    ],
    "destinationAddress": {
        "name": "Wile E. Coyote",
        "phoneNumber": "888-555-1234",
        "street1": "123 Main St.",
        "street2": "Suite 42",
        "city": "Albuquerque",
        "state": "NM",
        "countryCode": "US",
        "postalCode": "87121",
        "addressType": "commercial"
    },
    "shipFromAddress": {
        "name": "Ro Drunner",
        "phoneNumber": "5555555555",
        "emailAddress": "[email protected]",
        "company": "Sell It",
        "street1": "401 N. Centre St.",
        "city": "Pottsville",
        "state": "PA",
        "countryCode": "US",
        "postalCode": "17901"
    },
    "returnToAddress": {
        "name": "Rod Runner",
        "phoneNumber": "865-433-9999",
        "phoneNumberCountryCode": "+2",
        "emailAddress": "[email protected]",
        "company": "ACME",
        "street1": "456 Main St.",
        "street2": "Suite 8",
        "city": "Albuquerque",
        "state": "NM",
        "countryCode": "US",
        "postalCode": "87121",
        "addressType": "commercial"
    },
    "fulfillmentContextId": "1f19ca28-9798-42b2-9e8c-f9c3a72c9bab",
    "requestFulfillmentContextIds": [],
    "originId": "5a1ea728-4ba2-4cc6-892c-1f122f350775",
    "packagingType": {
        "packagingMaterial": "box",
        "linearDimensions": {
            "linearUnit": "in",
            "length": 15.0,
            "width": 10.0,
            "height": 5.0
        },
        "packagingWeight": {
            "weightUnit": "oz",
            "weight": 13.0
        }
    },
    "totalWeight": {
        "weightUnit": "oz",
        "weight": 13.0
    },
    "payorAccounts": [
        {
            "accountType": "consignee",
            "payorAccountCredentials": {
                  "accountNumber": "123456789",
                  "accountPostalCode": "98101"
                },
            "payorAccountAddress": {
                "name": "Rod Runner",
                "phoneNumber": "8654339999",
                "phoneNumberCountryCode": "+2",
                "emailAddress": "[email protected]",
                "company": "ACME",
                "street1": "456 Main St.",
                "street2": "Suite 8",
                "city": "Albuquerque",
                "state": "NM",
                "countryCode": "US",
                "postalCode": "87121",
                "addressType": "commercial"
            },
                "registrationInformation": {
                  "registrationNumber": "12344509"
              },
            "billForShippingCost": false,
            "billDutiesAndTaxes": false
        }
    ],
    "shipmentTags": [],
    "carrierSelection": {
        "status": "success",
        "statusDetails": "success",
        "carrierSelectionId": "911b488c-c620-4663-a554-bf9628e7ff43",
        "shipiumShipmentId": "3185ae04-d465-408a-9ae2-a98c7499e6bc",
        "partnerId": "76abb3d4-8990-4f80-aa13-4c2007cb852a",
        "carrierAccountId": "7b811704-9a16-4d3b-b849-43c7279415ac",
        "serviceMethodIdentifier": "1f19ca28-9798-42b2-9e8c-f9c3a72c9bab:dXBzbWktcGFyY2VsLXNlbGVjdC1zZXJ2aWNlLW1ldGhvZDo6NDNjYTI3ZDctZmUzNi00YjI1LTk4MDAtYTdmMTE2ZDIyMTQxOjdiODExNzA0LTlhMTYtNGQzYi1iODQ5LTQzYzcyNzk0MTVhYzpmZTFlMjg1Mi1kNTBiLTQ5OGQtOGIxMC05MGJiMWM5ODFjZTA6dXBzbWk6NWExZWE3MjgtNGJhMi00Y2M2LTg5MmMtMWYxMjJmMzUwNzc1Ojo",
        "carrier": "upsmi",
        "carrierServiceMethodId": "upsmi-parcel-select-service-method",
        "serviceMethodName": "UPS Mail Innovations Parcel Select",
        "totalCost": 1.0,
        "carrierCompareCost": 1.0,
        "carrierInvoiceCost": 1.0,
        "operationalCost": 1.0,
        "thirdPartyBilling": false,
        "carrierSelectionDateTime": "2024-03-25T19:44:22.232Z"
    },
    "saturdayDelivery": false,
    "deliverySignatureOption": "None",
    "forceThirdPartyBilling": false,
    "createdWithVersion": "v2",
    "multiParcel": false,
    "testMode": true
}

USPS payor information

Payor type	USPS supports payor type	USPS requires payor account credentials
`sender`	Yes	Yes
`third_party`	Yes	Yes
`consignee`	Yes	Yes
`recipient`	Yes	Yes

USPS required fields

USPS provides two different mechanisms to identify account information for payors. The USPS Direct CRID, USPS Direct MID, and USPS Direct Manifest MID are always required for either mechanism. After providing these three required values, you also will provide either the USPS Direct Account Number or the USPS Direct Permit Number and USPS Direct Permit ZIP.

The following fields must be included for USPS, depending on the supported payor type: sender, third party, consignee, or recipient.

Request field	Required/Optional	Field properties	Description
`payorAccounts.accountType`	Required for all payor types	String enumeration Values are: `consignee` `recipient` `sender` `third_party`	The type of account to use for billing
`payorAccounts.carrierId`	Required for `third_party` account type	String enumeration Ex.: `usps`	The carrier ID as represented in the Shipium platform; you can find carrier ID values in Supported Carriers.
`payorAccounts .payorAccountCredentials .accountNumber`	Conditional	String	Your organization's carrier account number used to authenticate and connect to the carrier's APIs; you must provide either an `accountNumber` OR a `permitNumber` and `permitPostalCode`.
`payorAccounts .registrationInformation .registrationNumber`	Required for `consignee` payor type; not required for `recipient`, `sender`, or `third_party`	String Ex.: `12344509`	The registration number for the payor account
`payorAccounts .additionalCarrier SpecificInformation.usps .customerRegistrationId`	Required for all payor types	String	USPS account Customer Reference/Registration ID
`payorAccounts .additionalCarrier SpecificInformation.usps .mailerId`	Required for all payor types	String	USPS account Mailer ID
`payorAccounts .additionalCarrier SpecificInformation.usps .manifest`	Required for all payor types	String	USPS account Mailer ID for manifesting
`payorAccounts .additionalCarrier SpecificInformation.usps .permitNumber`	Conditional	String	USPS permit number; you must provide either an `accountNumber` OR a `permitNumber` and `permitPostalCode`.
`payorAccounts .additionalCarrier SpecificInformation.usps .permitPostalCode`	Conditional	String	The ZIP code associated with your permit number; you must provide either an `accountNumber` OR a `permitNumber` and `permitPostalCode`.
`payorAccounts .billForShippingCost`	Required for all payor types	Boolean `true` or `false`	If `true`, this indicates whether the payor should be billed for the cost of shipping the package; the value should be `false` when designating tax ID (`EIN`) for a payor type (`typeCode`).
`payorAccounts .billDutiesAndTaxes`	Required for all payor types	Boolean `true` or `false`	If `true`, this indicates whether the payor should be billed for duties and taxes; the value should be `false` when designating tax ID (`EIN`) for a payor type (`typeCode`).

Sample request for consignee billing for USPS

This example shows the required payorAccounts information in JSON to be included via API call for billing for a consignee for USPS using the permit number and permit ZIP code.

{
  "accountType": "consignee",
  "additionalCarrierSpecificInformation": {
    "usps": {
      "customerRegistrationId": "123456789012345",
      "mailerId": "123456789",
      "manifest": "987654321",
      "permitNumber": "1111",
      "permitPostalCode": "43035"
    }
  },
  "registrationInformation": {
    "registrationNumber": "12344509"
  },
  "billForShippingCost": false,
  "billDutiesAndTaxes": false
}

Providing tax and registration numbers for payors

When specifying payor accounts for international shipments, you can provide tax identification and registration information for any party involved in the shipment using the registrationInformation object within payorAccounts. This is the primary method for providing tax identifiers such as EORI (Economic Operators Registration and Identification) numbers for consignees, importers of record (IORs), and other entities involved in international customs clearance.

What is registration information?

The registrationInformation object allows you to specify tax identification and registration numbers for entities other than the shipper. This capability is particularly important for international customs clearance, especially when shipping to or from the European Union, United Kingdom, and other countries that require EORI numbers or similar tax identifiers.

Unlike your organization's tax identification number (which is specified in customsInfo.taxIdentificationNumber), the registrationInformation object is used to provide tax identification for other parties in the shipment - such as the consignee, importer of record, or third-party payor.

When to use registration information

Use the registrationInformation object within payorAccounts when:

International shipments require EORI numbers. Many countries, particularly in the EU and UK, require EORI numbers for customs clearance. The consignee or importer of record must provide their EORI number for the shipment to clear customs.
The consignee or importer of record has a separate tax ID. When the entity receiving the shipment or acting as the importer of record is different from the shipper and needs to provide their own tax identification for customs purposes.
Customs clearance requires registration information for non-shipper entities. Various countries have specific tax identification or registration requirements for parties other than the shipper involved in international trade.
Multiple parties are involved in customs clearance. Complex international shipping arrangements where brokers, importers of record, or other third parties need to provide their tax identification information

Understanding tax ID methods in Shipium

Shipium's API provides multiple methods for tax identification information, each serving a distinct purpose.

Method	Location	Entity	Use case
Primary (Recommended)	`payorAccounts.registrationInformation`	Any payor (consignee, IOR, third party)	Providing EORI, VAT, or other tax identifiers for entities other than the shipper
Sender's Tax ID	`customsInfo.taxIdentificationNumber`	Shipper/Exporter only	Your organization's tax ID for export compliance
Alternative	`customsInfo.importerOfRecord` or `customsInfo.brokers`	IOR or Broker	Alternative method for specifying IOR/broker tax IDs

The payorAccounts.registrationInformation method is recommended for most use cases, particularly for EORI numbers, as it provides the clearest association between the party and their tax identification.

registrationInformation object structure

The registrationInformation object is included within the payorAccounts array and contains the following fields:

typeCode. String. Required. The type of registration number being provided; use "EOR" for EORI numbers. Use "EIN" for Employer Identification Numbers. Additional type codes may be supported for other tax identifier types.
registrationNumber. String. Required. The actual tax identification or registration number; format depends on the issuing country's requirements. For example, UK EORI numbers follow the format "GB123456789000" while other countries have different formats.
issuerCountryCode. String. Conditional. The ISO 3166-1 alpha-2 country code of the country that issued the registration number. This field is required for DHL Express and optional for other carriers such as UPS and FedEx. This must be a valid 2-character ISO country code (e.g., "GB" for United Kingdom, "DE" for Germany, "US" for United States).

API examples

Example 1: International shipment with EORI for UPS

This example shows an international shipment where the consignee has an EORI number that must be provided for customs clearance. The issuerCountryCode is optional for UPS.

{
  "shipmentParameters": {
    "partnerShipmentId": "INTL_SHIPMENT_001",
    "shippedDateTime": "2025-11-04T09:12:33.123456Z",
    "destinationAddress": {
      "name": "Jane Smith",
      "company": "UK Retail Ltd",
      "street1": "45 Commerce Street",
      "city": "London",
      "postalCode": "SW1A 1AA",
      "countryCode": "GB",
      "addressType": "commercial"
    },
    "customsInfo": {
      "taxIdentificationNumber": "12-3456789",
      "totalCustomsValue": 250.00,
      "totalCustomsValueCurrency": "usd",
      "customsDescription": "Electronics components",
      "reasonForExport": "sale",
      "incoterm": "ddp"
    },
    "payorAccounts": [
      {
        "accountType": "consignee",
        "payorAccountAddress": {
          "name": "Jane Smith",
          "company": "UK Retail Ltd",
          "street1": "45 Commerce Street",
          "city": "London",
          "postalCode": "SW1A 1AA",
          "countryCode": "GB"
        },
        "registrationInformation": {
          "typeCode": "EOR",
          "registrationNumber": "GB123456789000"
        }
      }
    ]
  }
}

Example 2: International shipment with EORI for DHL Express

When shipping with DHL Express, the issuerCountryCode field is required and must specify the ISO country code that issued the EORI number. In this example, the payorAccountCredentials and payorAccountAddress fields are not included. When these fields are omitted, Shipium will use the carrier account configured in your fulfillment context in the Shipium Console.

{
  "shipmentParameters": {
    "partnerShipmentId": "INTL_SHIPMENT_002",
    "shippedDateTime": "2025-11-04T09:12:33.123456Z",
    "destinationAddress": {
      "name": "Hans Mueller",
      "company": "German Imports GmbH",
      "street1": "Hauptstrasse 123",
      "city": "Berlin",
      "postalCode": "10115",
      "countryCode": "DE",
      "addressType": "commercial"
    },
    "customsInfo": {
      "taxIdentificationNumber": "12-3456789",
      "totalCustomsValue": 500.00,
      "totalCustomsValueCurrency": "usd",
      "customsDescription": "Industrial equipment",
      "reasonForExport": "sale",
      "incoterm": "ddp"
    },
    "payorAccounts": [
      {
        "accountType": "consignee",
        "registrationInformation": {
          "typeCode": "EOR",
          "issuerCountryCode": "DE",
          "registrationNumber": "DE987654321000"
        }
      }
    ]
  }
}

Example 3: Multi-parcel international shipment with EORI

For multi-parcel shipments, the registrationInformation object is included in the multiParcelShipmentParameters.

{
  "multiParcelShipmentParameters": {
    "partnerShipmentId": "MULTIPARCEL_INTL_001",
    "shippedDateTime": "2025-11-04T09:12:33.123456Z",
    "destinationAddress": {
      "name": "Marie Dubois",
      "company": "French Distribution SA",
      "street1": "12 Rue du Commerce",
      "city": "Paris",
      "postalCode": "75001",
      "countryCode": "FR",
      "addressType": "commercial"
    },
    "customsInfo": {
      "taxIdentificationNumber": "12-3456789",
      "totalCustomsValue": 1200.00,
      "totalCustomsValueCurrency": "usd"
    },
    "payorAccounts": [
      {
        "accountType": "consignee",
        "registrationInformation": {
          "typeCode": "EOR",
          "issuerCountryCode": "FR",
          "registrationNumber": "FR12345678900"
        }
      }
    ],
    "packages": [
      {
        "weight": 15,
        "weightUnit": "lb",
        "dimensions": {
          "length": 12,
          "width": 10,
          "height": 8,
          "dimensionUnit": "in"
        }
      },
      {
        "weight": 20,
        "weightUnit": "lb",
        "dimensions": {
          "length": 14,
          "width": 12,
          "height": 10,
          "dimensionUnit": "in"
        }
      }
    ]
  }
}

Carrier-specific requirements for international shipments

Different carriers have varying requirements for tax identification and registration information in international customs clearance:

UPS International
- Supports EORI numbers via registrationInformation object
- The issuerCountryCode field is optional.
- EORI information will appear on UPS commercial invoices for customs clearance.
- Compatible with UPS Worldwide Express, UPS Worldwide Expedited, and other UPS international service methods
DHL Express
- Supports EORI numbers via registrationInformation object
- The issuerCountryCode field is required for DHL Express shipments.
- DHL Express uses this information for customs clearance in destination countries.
- Particularly important for shipments to and from European Union countries
FedEx International
- Supports EORI numbers via registrationInformation object
- The issuerCountryCode field is optional.
- EORI information appears on FedEx international shipping documents.

Contact your Implementation or Customer Success team member to confirm carrier-specific formatting requirements for your destination countries.

Common international shipping scenarios

Shipping to EU Countries with EORI Requirements
When shipping to European Union member countries, the consignee typically needs an EORI number for customs clearance. Include the EORI number in registrationInformation with the appropriate issuerCountryCode for the destination country.
Shipping to UK Post-Brexit
United Kingdom EORI numbers are now distinct from EU EORI numbers. Use country code "GB" for UK EORI numbers, and ensure you have the correct EORI format for post-Brexit shipments.
Delivered Duty Paid (DDP) Shipments
For DDP incoterm shipments where your organization pays duties and taxes, you may still need to provide the consignee's EORI number for customs clearance purposes, even though you're responsible for payment.
Using Customs Brokers
When using a customs broker, you may need to provide the broker's tax identification information in addition to the consignee's information. The Broker & Importer of Record documentation provides details on designating brokers.

Account number requirements

When using the payorAccounts object with registrationInformation, you have flexibility in providing account credentials:

With explicit account number. Include payorAccountCredentials.accountNumber to specify a particular carrier account for billing. This is useful when billing a specific third-party account for the international shipment.
Without explicit account number. Omit the payorAccountCredentials object entirely, and Shipium will use the carrier account configured in your fulfillment context in the Shipium Console. This simplifies API calls when you're not using third-party billing but still need to provide registration information for customs.

Example with account number

"payorAccounts": [
  {
    "accountType": "consignee",
    "payorAccountCredentials": {
      "accountNumber": "987654321"
    },
    "registrationInformation": {
      "typeCode": "EOR",
      "registrationNumber": "GB123456789000"
    }
  }
]

Example without account number (uses Console configuration)

"payorAccounts": [
  {
    "accountType": "consignee",
    "registrationInformation": {
      "typeCode": "EOR",
      "issuerCountryCode": "GB",
      "registrationNumber": "GB123456789000"
    }
  }
]

Resources

Your Shipium team member is available to help along the way. However, you might find these resources helpful:

About specifying payors

Specify payor details in calls to Shipium's APIs

Account information included via API call in payorAccounts will override account credentials configured in the Shipium Console.

Payor request details

Carrier-specific information for payors

DHL payor information

DHL required fields

Sample request for consignee billing for DHL

FedEx payor information

FedEx required fields

Sample request for recipient billing for FedEx

Midland payor information

Midland required fields

Sample request for sender billing for Midland

OnTrac payor information

OnTrac required fields

Sample request for third party billing for OnTrac

Purolator E-Ship payor information

Purolator E-Ship required fields

Sample request for third party billing for Purolator E-Ship

UPS payor information

UPS required fields

Sample request for recipient billing for UPS

Sample request for consignee billing for UPS

Sample response for consignee billing for UPS

USPS payor information

USPS required fields

Sample request for consignee billing for USPS

Providing tax and registration numbers for payors

What is registration information?

When to use registration information

Understanding tax ID methods in Shipium

registrationInformation object structure

API examples

Example 1: International shipment with EORI for UPS

Example 2: International shipment with EORI for DHL Express

Example 3: Multi-parcel international shipment with EORI

Carrier-specific requirements for international shipments

Common international shipping scenarios

Account number requirements

Example with account number

Example without account number (uses Console configuration)

Related documentation

Resources