About specifying payors

The Shipium system supports billing multiple payor accounts separately for costs associated with a shipment. Different carriers support different payor types and require varying data for each payor type. The following table is meant to give an overview for supported carriers and payor types for the most common carriers used by Shipium customers. Details on payor account credential information are included in the request fields table below.

Carrier-specific payor support

Payor type	Carrier	Carrier supports payor type	Carrier requires payor account credentials
`sender` (default)	FedEx	Yes	Yes
`sender` (default)	UPS	Yes	Yes
`sender` (default)	Midland	Yes	No
`third_party`	FedEx	Yes	Yes
`third_party`	UPS	Yes	Yes
`third_party`	Midland	Yes	Yes ✳️
`collect`	FedEx	Yes	Yes
`collect`	UPS	No	Not Applicable (N/A)
`collect`	Midland	Yes	No
`consignee`	FedEx	No	N/A
`consignee`	UPS	Yes	No
`consignee`	Midland	No	N/A
`recipient`	FedEx	Yes	Yes
`recipient`	UPS	Yes	Yes
`recipient`	Midland	No	N/A

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

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.

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 request details

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` (default) - `third_party`	The type of account to use for billing
`payorAccounts.carrierId`	Required	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 recipient
`payorAccounts .payorAccountAddress .phoneNumber`	Optional	String	The phone number of the shipment recipient
`payorAccounts .payorAccountAddress .phoneNumberCountryCode`	Optional	String	The phone number country code of the shipment recipient
`payorAccounts .payorAccountAddress .emailAddress`	Optional	String	The email address of the shipment recipient
`payorAccounts .payorAccountAddress .company`	Optional	String	The company associated with the shipment recipient
`payorAccounts .payorAccountAddress .street1`	Optional	String	The first address line for the shipment recipient
`payorAccounts .payorAccountAddress .street2`	Optional	String	The second address line for the shipment recipient
`payorAccounts .payorAccountAddress .city`	Optional	String	The city of the address for the shipment recipient
`payorAccounts .payorAccountAddress .state`	Optional	String	The two-letter postal abbreviation of the state for the shipment recipient's address
`payorAccounts .payorAccountAddress .countryCode`	Required	String	The ISO 3166-1 country code for the shipment recipient's address
`payorAccounts .payorAccountAddress .postalCode`	Required	String	A country-code-appropriate postal code for the shipment recipient's address
`payorAccounts .payorAccountAddress .addressType`	Optional	String enumeration Values are: - `commercial` - `residential`	The type of location for the shipment recipient'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: - `VAT` (value added tax) - `EIN` (employee identification number)	The registration number type code for the payor account
`payorAccounts .registrationInformation .registrationNumber`	Optional	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 default value is `true`.
`payorAccounts .billDutiesAndTaxes`	Required	Boolean `true` or `false`	If `true`, this indicates whether the payor should be billed for duties and taxes. The default value is `true`.

Sample request for recipient billing (UPS)

This example shows the payorAccounts information in JSON to be included via API call for billing for a recipient. The request fields are described in the table following the example, which demonstrates inclusion within shipmentParameters.

{
  ....
  "shipmentParameters": {
    "payorAccounts": [
      {
        "accountType": "recipient",
        "carrierId": "ups",
        "payorAccountCredentials": {
          "accountNumber": "123456789",
          "accountCountryCode": "US",
          "accountPostalCode": "98101"
        },
        "payorAccountAddress": {
          "name": "Wile E. Coyote",
          "phoneNumber": "string",
          "phoneNumberCountryCode": "+1",
          "emailAddress": "[email protected]",
          "company": "ACME",
          "street1": "123 Main St.",
          "street2": "Suite 42",
          "city": "Albuquerque",
          "state": "NM",
          "countryCode": "US",
          "postalCode": "87121",
          "addressType": "commercial"
        },
        "registrationInformation": {
          "typeCode": "VAT",
          "registrationNumber": "1234567-123",
          "issuerCountryCode": "US"
        },
        "billForShippingCost": true,
        "billDutiesAndTaxes": true
      }
    ]
  },
  "generateLabel": true,
  "labelParameters": {
    ....
  }
  ....
}

Sample request and response for consignee billing

This example shows the payorAccounts information in JSON to be included via API call for billing for a consignee. The request fields are described in the table following the example, which demonstrates inclusion within shipmentParameters.

Sample request for consignee billing (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",
                "carrierId": "ups",
                "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"
                },
                "billForShippingCost": true,
                "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 (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",
            "carrierId": "ups",
            "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"
            },
            "billForShippingCost": true,
            "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
}

Resources

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