Bill a Third Party

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, Midland, OnTrac, 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.

Preferred workflow for third party billing configuration

Shipium offers two workflows for configuring third party billing in the console. The instructions in this document route through Configure → Fulfillment Configuration. The preferred workflow routes through Configure → Fulfillment Contexts, where third party billing can be configured directly within the context you wish to associate it with. You can find instructions for the preferred workflow in the Third Party Billing document.

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:

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. 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."

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. 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 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.

After you've successfully populated the Billing Group ID, you'll need to select the Add New Third Party Billing Account button to create a new third party billing account.

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.

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. You may choose, however, to update the Group Name field to a title with spaces and special characters.

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. 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.

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.

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 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.

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

{
  "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.

{
  "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.

{
    "shipiumShipmentId": "7f38748a-eb35-40c1-9b3c-a9eb52fd9f21",
    "requestThirdPartyBillingSetId": "company-x",
    "partnerThirdPartyBillingSetId": "company-x",
    "forceThirdPartyBilling": false,
    "carrierSelection": {
        "status": "success",
        "carrier": "ups",
        "totalCost": 11.5,
    },
    "carrierLabel": {
        "status": "success",
        "carrier": "ups",
    }
}

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.

{
  "shipmentParameters": {
    "payorAccounts": [
      {
        "accountType": "third_party",
        "carrierId": "ups",
        "payorAccountCredentials": {
          "accountNumber": "901273654",
          "accountCountryCode": "US",
          "accountPostalCode": "98101"
        },
        "payorAccountContact": {
          "name": "Betty Rubble",
          "company": "Slate",
        },
        "billForShippingCost": true,
        "billDutiesAndTaxes": true
      }
    ]
  }
}

Resources

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