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.

The Shipium platform supports third party billing for FedEx and United Parcel Service (UPS) carriers shipping domestically in the U.S. and shipping internationally. FedEx and UPS will bill shipping charges to a party other than the shipper or receiver. However, to configure third party billing for your organization within the Shipium platform, you first must have an established contract for your fulfillment context for the desired carrier, either FedEx or UPS.

👍
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 and use your third party billing account

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, FedEx and/or UPS. After you've set up third party billing with FedEx and/or UPS, 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. At most, any group will have two accounts, one for FedEx and one for UPS. 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.

Set up third party billing for your organization via the Shipium Console

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.

Creating 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 FedEx or UPS as 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, whether for FedEx or UPS. While FedEx requires only the third party's account number, UPS requires the account number, postal code, and country code. 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, whether FedEx or UPS.

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, 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": [...]
    },
    ....
}

Resources

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

Bill a Third Party

About third party billing

👍
Alternative workflow instructions for setting up a third party billing account

Set up and use your third party billing account

🚧
404 error

Set up third party billing for your organization via the Shipium Console

Creating third party billing groups and accounts

👉
Groups should be linked to your Fulfillment Context(s)

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

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

Manage your third party billing accounts

Use Shipium APIs for third party billing

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

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

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

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

Expected response from the API call

👉
Total cost calculated

Resources

About third party billing

👍Alternative workflow instructions for setting up a third party billing account

Set up and use your third party billing account

🚧404 error

Set up third party billing for your organization via the Shipium Console

Creating third party billing groups and accounts

👉Groups should be linked to your Fulfillment Context(s)

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

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

Manage your third party billing accounts

Use Shipium APIs for third party billing

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

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

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

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

Expected response from the API call

👉Total cost calculated

Resources

👍
Alternative workflow instructions for setting up a third party billing account

🚧
404 error

👉
Groups should be linked to your Fulfillment Context(s)

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

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

👉
Total cost calculated