About third party billing

Third party billing allows your organization to bill another account, or third party, for the cost of shipping a package. For example, your organization may need to bill Company X for a business-to-business (B2B) order shipment, using Company X's carrier account rates. You also might wish to bill two different accounts for the shipment: one for shipping fees and one for taxes and duties associated with the shipment.

The Shipium platform supports third party billing for carriers including Canada Post, DHL, FedEx, Purolator E-Ship, UPS, and USPS Direct shipping domestically in the U.S. and shipping internationally. Carriers will bill shipping charges to a party other than the shipper or receiver.

You can configure third party billing account details in the Shipium Console, or you can send account details via calls to Shipium's APIs. This document includes instructions for both methods.

👍

Alternative workflow instructions for setting up a third party billing account

You can find instructions for setting up a third party billing account within the suggested fulfillment contexts workflow in the Third Party Billing document. You also may follow the guidance in this document to set up third party billing within the fulfillment configuration workflow.

Set up your third party billing account via the Shipium Console

To enable third party billing for your Shipium account, you'll first need to create a third party billing carrier account with your desired carrier. After you've set up third party billing with your carrier, you'll be ready to create your Shipium third party billing account(s) and third party billing group(s) within the Shipium Console.

The third party billing account is an individual carrier account you create for billing a third-party entity. The third party billing group organizes third party billing accounts into a single group for a simpler workflow. For example, your organization may wish to set up two separate carrier accounts for Company X, a FedEx carrier account and a UPS carrier account. In this case, as an example, you would have:

• Third Party Billing Group: Company-X
• Third Party Billing Accounts within the Company-X Third Party Billing Group
  • Third Party Billing Account for FedEx: Company-X-FedEx
  • Third Party Billing Account for UPS: Company-X-UPS

Once you've established at least one third party billing group, you'll need to link the group to your Fulfillment Context. Then you can include your organization's third party billing information in your calls to Shipium's application programming interfaces (APIs) to bill a third party for shipments.

🚧

404 error

If your organization includes third party billing in your call to the Shipium API but no third party billing is set up for your Fulfillment Context, you'll receive a 404 error message.

Once you've accessed the Shipium Console, you'll need to navigate to Configure, then Fulfillment Configuration, as shown in the following screenshot.

Within Fulfillment Configuration, you'll scroll down to the Carrier Selection Configuration category, which includes Third Party Billing Groups and Third Party Billing Accounts. You'll select Third Party Billing Groups to set up your organization's third party billing. Once you've created at least one account within your group(s), you'll be able to make changes to the account by selecting Third Party Billing Accounts.

Create third party billing groups and accounts

Within Third Party Billing Groups, you can configure details required to bill shipments to a third party.

👉

Groups should be linked to your Fulfillment Context(s)

Once you've created a Third Party Billing Group, you'll want to link it to any of your organization's network Fulfillment Contexts.

To add a new third party billing group for the first time, you'll need to select either the Add Third Party Billing Group button or the + button next to the card entitled "Third Party Billing Group," as shown in the following screenshot.

To add a new third party billing group when you already have existing third party billing groups, you'll need to select the Add Third Party Billing Group button, as shown in the following screenshot. Your existing third party billing groups will be listed on the same screen.

Next, you'll need to provide a Billing Group ID, which should be a unique ID that you'll use to reference this billing group, or set, in your Carrier Selection API calls. Your Billing Group ID must be composed of only alphanumeric characters, hyphens, and underscores. Otherwise, you'll receive an error warning, as shown in the following screenshot. This unique ID is case sensitive.

You'll select the Continue button once you've provided the Billing Group ID.

After you've successfully populated the Billing Group ID (as indicated by the green checkmark at left of Billing Group ID in the screenshot below), you'll need to select the Add New Third Party Billing Account button to create a new third party billing account.

If you already have an established account for the new third party billing group you're creating, you'll be able to select it from the dropdown menu rather than adding a new account.

To add a new third party billing account within your third party billing group, you'll need to select the carrier, as well as provide an account identifier, name, and optional description. The Name field auto-populates from the Identifier field, which is restricted to alphanumeric characters, hyphens, and underscores. You may choose, however, to update the Name field to a title with spaces and special characters.

When you create a new account, you'll also determine the person responsible for both shipment fees and taxes and duties for the shipping label. The default value for each is "3rd Party".

To link your new third party billing account for third party billing, you'll also need to provide the carrier billing account credentials, which differ by carrier. UPS provides a list of its accepted two-letter country codes.

You'll select the Save button once you've added a new account or selected an existing account from the dropdown menu, at which point you'll be returned to the Third Party Billing Group where you can add more accounts. You should see the account you just created populated in the field for Billing Group ID (Company-X-FedEx in this example). You may choose to add another account to this third party billing group by repeating the steps to Add New Third Party Billing Account, or select the Continue button.

Once you've added the third party billing accounts to be associated with your third party billing group, you'll be asked to name the group. The Group Name field auto-populates from the Billing Group ID field, which is restricted to alphanumeric characters, hyphens, and underscores. You may choose, however, to update the Group Name field to a title with spaces and special characters.

You'll have a chance to review your Third Party Billing Group Summary before selecting the Save button. The following screenshot demonstrates that two new third party billing accounts, Company-X-FedEx and Company-X-UPS, comprise the newly created third party billing group Company-X.

Once saved, you'll see a notification onscreen that "your configuration has been saved successfully" and the new group will display on your Third Party Billing Groups screen, along with an accompanying Actions dropdown menu.

To modify or delete an existing third party billing group, you'll need to select the Actions dropdown menu, as shown in the previous and following screenshots. To edit the group, you'll select Edit Third Party Billing Group. To delete the group, you'll select Delete.

You can also select Detail from the dropdown Actions menu for additional details for that third party billing group.

Link your third party billing groups and accounts to your Fulfillment Context(s)

To bill a third party for a shipment, you'll first need to link your third party billing group to at least one of your fulfillment contexts. To access your fulfillment contexts, you'll need to select Configure and then Fulfillment Configuration from the main lefthand navigation menu. Then you'll scroll down to the Carrier Selection Configuration category.

Within Fulfillment Contexts, you can access the fulfillment context with which you wish to associate your third party billing group from the list of your organization's existing fulfillment contexts (you also can create a new one). For this example, Valerian Vessels is the name of the fulfillment context.

To add a third party billing group to your existing (or newly created) fulfillment context, you'll need to select Edit a Fulfillment Context from the Actions dropdown menu to the right of the desired fulfillment context.

🚧

Third party billing carrier contract must be set up in your fulfillment context

To successfully link a Third Party Billing Group to your Fulfillment Context, the context must include a contract for the associated carrier.

Selecting Edit a Fulfillment Context takes you to the primary screen for that fulfillment context, where you should select Third Party Billing Group Select. Then you should choose the desired third party billing group from the dropdown menu in the field at right, as shown in the following screenshot. For this example, the third party billing group created earlier, Company-X, has been selected.

Manage your third party billing accounts

To access your third party billing accounts, you'll need to select Configure and then Fulfillment Configuration from the main lefthand navigation menu. Then you'll scroll down to the Carrier Selection Configuration category where you'll select Third Party Billing Accounts.

Within Third Party Billing Accounts, you can update or delete your organization's billing accounts for third parties.

To modify or delete an existing third party billing account, you'll need to select either the Edit Third Party Billing Account button or Delete button OR the edit icon in the title within the card on screen bearing the title of the desired third party billing account. The following screenshot displays the two example accounts created for the Company-X third party billing group, Company-X-UPS and Company-X-FedEx.

You can also select the Detail button on any third party billing account's card for additional details for that third party billing account.

Use Shipium APIs for third party billing

If your organization would like to bill a shipment to a third party when calling the Shipium APIs and you configured your third party billing account via the Shipium Console, you'll reference the identification (ID) of the third party billing group, or set, in the shipmentParameters. You may use either the Billing Group ID or the Shipium-generated ID for the set.

To use third party billing for international shipments, you'll need to add a customsInfo object to the request body in the API call. For support shipping internationally, you can refer to Customs Info for Shipments.

🚧

Your third party billing account must be set up before calling the APIs

When your organization calls the APIs, Shipium will bill the third party for the shipment if there is a third party billing account for the carrier and service method that is chosen via Carrier Selection.

Pass third party billing group (set) information in shipment parameters

This example shows the shipmentParameters information in JavaScript Object Notation (JSON) to be included via API call.

{
  ....
  "shipmentParameters": {
    "thirdPartyBillingSetId": "company-x" or "cf3daf7d-6fca-46c2-9d9e-30a476dcc1e4" //partnerProvidedId or shipiumId for the thirdPartyBillingSet
    ....
    ....
  },
  "generateLabel": true,
  "labelParameters": {
    ....
  }
  ....
}

Use a boolean flag to force third party billing information in shipment parameters

If your organization would like to guarantee that a shipment is billed to a third party, you can pass a boolean flag forceThirdPartyBilling in the shipmentParameters. When this flag is set to true, Shipium will only consider service methods for which there is a corresponding third party billing account. This example shows the boolean forceThirdPartyBilling in JSON to be included in the shipmentParameters.

{
  ....
  "shipmentParameters": {
    "thirdPartyBillingSetId": "company-x",
    "forceThirdPartyBilling": true,
    ....
    ....
  },
  "generateLabel": true,
  "labelParameters": {
    ....
  }
  ....
}

Select a carrier and service method to be used for third party billing

If your organization would like to select which carrier and service method will be used for billing a third party, you can use the carrierServiceMethodAllowList to select one service method. You must have your third party billing account set up for the carrier of the requested service method for this call to be successful. This example shows use of the carrierServiceMethodAllowList information in JSON to be included in the API call.

{
  ....
  "carrierServiceMethodAllowList": ["ups-2nd-day-air-service-method"], 
  "shipmentParameters": {
    "thirdPartyBillingSetId": "company-x",
    "forceThirdPartyBilling": true,
    ....
    ....
  },
  "generateLabel": true,
  "labelParameters": {
    ....
  }
  ....
}

Expected response from the API call

On the API response for a third party billing request, you will see the thirdPartyBillingSetId that was requested as well as the forceThirdPartyBilling flag. For thirdPartyBillingSetId, your API response will include the company name of the third party you selected for billing. Unless you enabled a forced third party billing, forceThirdPartyBilling will be set to false.

In the carrierSelection block, you'll see the boolean flag isThirdPartyBilling. This flag indicates if the service method selected can be billed to a third party billing account. If it can, the value for this flag will appear as true.

In the carrierLabel block, you'll see shipiumThirdPartyBillingAccountId and partnerThirdPartyBillingAccountId. Together, these fields indicate which third party billing account the shipment will use for billing.

👉

Total cost calculated

The totalCost field calculated in the carrierSelection block of the API return call reflects your organization's own rates, not the third party's rates.

Note: The carrierLabelPrice in the carrierLabel block will likely be inaccurate and appear as a zero-dollar amount (0.0), unless your organization has established permission with the carrier to view the third party’s rates.

{
    "shipiumShipmentId": "7f38748a-eb35-40c1-9b3c-a9eb52fd9f21",
    ....
    "requestThirdPartyBillingSetId": "company-x",
    "partnerThirdPartyBillingSetId": "company-x",
    "shipiumThirdPartyBillingSetId": "9v38748a-eb35-40c1-9b3c-a9eb52fd9d12",
    "forceThirdPartyBilling": false,
    ....
    "carrierSelection": {
        "status": "success",
        ....
        "carrier": "ups",
        "carrierServiceMethodId": "ups-2nd-day-air-service-method",
        "serviceMethodName": "UPS 2Day",
        "isThirdPartyBilling": true,
        "totalCost": 11.5, <-- this will be the cost calculated off of your rates
        ....
    },
    "carrierLabel": {
        ....
        "status": "success",
        "carrier": "ups",
        "serviceMethodName": "UPS 2Day",
        "carrierServiceMethodId": "ups-2nd-day-air-service-method",
        "shipiumThirdPartyBillingAccountId": "5g38748a-eb35-40c1-9b3c-a9eb52fd9f24",
        "partnerThirdPartyBillingAccountId": "company-x-UPS-account",
        "carrierLabelPrice": 0.0, <-- this will likely be inaccurate if you do not have permission to view the third party's rates
        "documents": [...]
    },
    ....
}

Include third party billing account details in API calls, without Shipium Console configuration

If your organization needs to include third party billing account information in calls to Shipium's APIs without configuring your third party billing account in the Shipium Console, you can include the payorAccounts object in the shipmentParameters or multiParcelShipmentParameters of your call. Requirements differ by carrier; you can find carrier-specific information in the Specifying Payors document.

If you have third party billing configured in the Shipium Console, any values included in the payorAccounts array of your API call will override your configurations in the console.

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

{
  ....
  "shipmentParameters": {
    "payorAccounts": [
      {
        "accountType": "third_party",
        "carrierId": "ups",
        "payorAccountCredentials": {
          "accountNumber": "901273654",
          "accountCountryCode": "US",
          "accountPostalCode": "98101"
        },
        "payorAccountContact": {
          "name": "Betty Rubble",
          "company": "Slate",
          "address1": "1204",
          "address2": "Rock Lane",
          "city": "Bedrock",
          "region": "WA",
          "postalCode": "98101",
          "countryCode": "US",
          "phoneNumber": "801-295-6767",
          "phoneNumberCountryCode": "US",
          "emailAddress": "[email protected]",
          "residential": false
        },
        "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": "0972354-110",
          "issuerCountryCode": "US"
        },
        "billForShippingCost": true,
        "billDutiesAndTaxes": true
      }
    ]
  },
  "generateLabel": true,
  "labelParameters": {
    ....
  }
  ....
}

Resources

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

• Terms and Definitions

• Troubleshooting Guide

• Contact Shipium Support