Skip to content

Supply Chain Partner Relationships

Copyright IBM Corporation and GTD Solution Inc. 2018, 2021

Multiple companies in the Supply Chain Management (SCM) industry are frequently interacting with each other, but there has traditionally been no efficient method of seamlessly connecting these organizations with each other as business partners. Individual organizations have different account management processes and architecture. The objective of the Supply Chain Partner Relationships feature is to connect this ecosystem and be the digital backbone of the global SCM industry. This functionality is the beginning of a process that will allow the network members to own these relationships, facilitating the process of sharing visibility to shipment data and trade objects. Business partners can search for each other and establish a partnership. The feature can be used through the UI or through the Business Partners API and requires organization admin authority.

Basic functions include:

  • An organization can search and invite the companies that are also part of the TradeLens platform to become business partners.
  • An organization has the option of being “searchable” or not.
  • An organization has the option to either accept or reject the partnership requests.
  • An organization can refer to a partner using a party identifier, either user specified, or system generated.

Once a business partnership has been established, the party identifier can be used to give the party access to a trade object, like a shipment, consignment, or transport equipment. Either a user specified party identifier or the system generated party identifier can be used.

Example Scenario: Carriers will usually be searchable and might have auto accept set for incoming business partner requests. A transport service buyer (shipper) will search for a transport service provider (carrier) and send the partner request. The carrier will auto accept the request and add party identifiers for the business partner relationship for all of the customer owned codes, or customer identification codes, that are used within the carrier's systems to identify the transport service buyer (shipper). Then the carrier will create the consignment (if it does not already exist) and add the transport service buyer to the consignment using their party identifier from the business partner relationship.

The management and operation of the feature is administered in two places: Organization Management and Business Partners.

Organization Management

When an organization is onboarded to the TradeLens platform, the onboarding team will include optional information about an organization, such as address, city, country, state, and postal code.

Within the organization management section, an organization can select the option to be searchable and this will allow other organizations to easily find business partners through search. An organization can also choose whether to auto approve (accept) incoming business partner requests. The default for searchable and auto approve is true. Organization Management can be accessed through the UI or the APIs.

The organization management section can be found in the UI by clicking on Account and then Organization Management. As shown below, the organization can select to be searchable and to automatically accept business partner requests.

Business Partners1c.png

The organization management APIs can be found in the Business Partners API drop-down in Swagger. See the API User Guide section for a link to the TradeLens APIs. The APIs are:

  • GET ...​/profile​/organization - Returns the organization's Business Partner profile
  • PATCH ...​/profile​/organization - Updates the organization's Business Partner profile
  • GET ...​/organizations - List all searchable organizations in TradeLens Platform

In the above image from the UI, if we want to change the organization so that it auto accepts incoming business partner requests, we could do this from the UI, or through the PATCH .../profile​/organization API.

Business Partners2a.png

Business Partners

The business partners function can be accessed through the UI or the APIs. A typical business partner scenario will consist of:

  1. Search for an organization by name.
  2. Select the organization, add a reference (or multiple references) for the receiving partner (optional at this step and can be done later if desired), and send the business partner request.
  3. Wait for a response from the receiving partner.
  4. Once the receiving partner approves the request, both organizations are in the business partner relationship. The receiving partner can add a reference (or multiple references) for the sending partner.

Note: When a new organization is onboarded, it should be available for business partners within about 5 minutes.

The business partners section can be found in the UI by clicking on Account and then Business Partners.

Business Partners3c.png

The business partner APIs can be found in the Business Partners API drop-down in Swagger. See the API User Guide section for a link to the TradeLens APIs. The APIs are:

  • GET ...​/partners - List the business partners and requests for the current organization
  • POST ...​/partners - Send business partner requests to a list of organizations
  • PATCH ...​/partners - Change the status of multiple business partner requests
  • PUT ...​/partners - Replace references associated with a particular partner Id
  • DELETE ...​/partners - Delete the specified reference from the business partnership
  • PUT ...​/partners​/bulk - Upload a CSV file to update partnership references

States of partnership

There are five allowed states for a business partnership:

  • Requested - sender will see this status until recipient takes action, state can be specified on API by sender.
  • Pending - recipient will see this status for requests that have been sent to recipient but not acted upon, state can not be specified on API.
  • Accepted - sender and recipient will see this status for requests that have been accepted by the recipient, state can be specified on API by recipient.
  • Denied - sender and recipient will see this status for requests that have been denied by the recipient, state can be specified on API by recipient.
  • Deleted - sender and recipient will see this status for partnerships that have been deleted by either party, state can be specified on API by either sender or recipient.

The table below shows possible states of a partnership between orgA and orgB.

Action Status in orgA Status in orgB
orgA sends request to orgB requested pending
orgB approves orgA's request accepted accepted
orgB denies orgA's request denied denied
either org deletes the relationship deleted deleted

Adding a business partner to a shipment, consignment, or transport equipment

Once a business partner relationship is complete, the party identifier that was used for the organization (or the system generated party identifier) can be specified as the partyRef on the partyAdded APIs POST ...​/shipments​/partyAdded - Shipment party added, POST ...​/consignments​/partyAdded - Consignment visibility added (E001) and POST ...​/transportEquipment​/partyAdded - Transport equipment visibility added (E550). We will show this step near the end of the example below.

Business Partner Rules

Business partner rules offer a simple and straight-forward method for your contracted service providers such as customs house broker (CHB) and 3PL, to have visibility and be involved in your consignments, without the need for your team to manually perform API calls for partyAdded. The Permissions section in the Business Partners UI provides the option to set up a business partner rule where you can specify a Rule, Condition, Party Role, and optional Start and End Dates to indicate if there is a date range for the rule to be active. This rule section is also in the Active & Declined Business Partners section if we edit a partnership. Any organization type can set up business partner rules, but the rule will only be checked if the organization that set the rule is a TRANSPORT_SERVICE_BUYER (TSB) or a TRANSPORT_SERVICE_PROVIDER (TSP). So if your organization is a TSB for the consignment (or becomes a TSB for the consignment), the rule(s) that you have configured will be checked and if the condition matches, your business partner will be added to the consignment with the party role that you have specified.

A specific example of when this feature is applicable is if a given Cargo Interest (TSB) works with one specific client partner for a specific set role when a given condition happens.

  • Cargo Interest ABC Wines - has a contract with Custom House Broker "Clearance Inc." for all their Imports into the United States.

  • Cargo Interest ABC Wines - has a contract with 3PL "Logistics r Us" for all their Export Logistics outside of the port of Algeciras, Spain.

An ABC Wines organization admin can go to the TradeLens Business Partner UI and indicate the above rules to be associated to their two business partners:

  • Organization "Clearance Inc." to be set as "Import Customs Broker" for all my consignments with Destination Location = United States of America.

    For the business partnership we have with "Clearance Inc.", we would specify: Business Partners3a1.png

  • Organization "Logistics r Us" to be set as "Origin 3PL Agent" for all my consignments with Origin Location = ESALG (Algeciras, Spain).

    For the business partnership we have with "Logistics r Us", we would specify: Business Partners3a2.png

Establishing a Business Partnership Example

In this example we will have two organizations. Organization1 will be a transport service buyer (shipper) and organization2 will be a transport service provider (ocean carrier). The shipper will search for an ocean carrier, request a partnership and add a party identifier for the carrier. The carrier will accept the request and add a party identifier for the shipper. The carrier will use the party identifier that they specified for the shipper to add the shipper to a consignment.

As discussed in the Organizational Management section above, the ocean carrier has set the option to be searchable. The shipper searches for the carrier in the Business Partners section of the UI, or by using the GET ...​/organizations - List all searchable organizations in TradeLens Platform API. In the image below, once we find the carrier we want to use, we click the Send Request button.

Business Partners4b.png

The shipper can fill in a name and party identifier for the carrier by either clicking the Input Manually button or use the option of Upload via CSV; we will use the Input Manually button in our example. The party identifier can be a customer owned code or an existing customer identification code, that the shipper uses within their existing systems to identify the carrier. Specifying a user defined party identifier is optional and it can be done later (by editing the partner in the Active Business Partners section) or the system generated party identifier can be used. When we are done editing a party identifier line, we click Send to save the party identifier information and send the request to the carrier. Note: If we already have an established business partnership and we are adding a party identifier, then we would click the Save Identifiers button.

Business Partners5c.png

The same function using the POST ...​/partners API is shown below. Notice that the code parameter is the party identifier that can be used as the partyRef on the partyAdded APIs to add the party to a trade object (shipment, consignment, or transport equipment).

Business Partners6a.png

In our case, the carrier has set the option within organizational management to auto approve, so the business partnership request from the shipper is established and displayed in the Active section. If the carrier did not have auto approve set, then we would see pending requests for the carrier within the business partner UI and we could click Accept. The corresponding API is PATCH ...​/partners and as the carrier, we would set the status as "accepted".

Business Partners7d.png

The carrier can add a party identifier for the shipper, and this party identifier can then be used as the partyRef for the partyAdded API to add the shipper to a consignment. Notice there is a Reference Added column that indicates if there is already an existing party identifier. In the second image below, there is also a system generated party identifier and it can be used as the partyRef for the partyAdded API. We find the shipper in the active business partners section and click edit to add or edit one or more party identifiers and then click Save Identifiers.

Business Partners9d.png Business Partners11d.png

If the carrier had autoApprove set to false, they can manually accept a new request and add a party identifier at the same time using the PATCH ...​/partners API; this scenario is shown below. Or they could approve the request using the PATCH API and add party identifier(s) later (also using the PATCH API with the reference id of the partnership) if desired. Notice that the code parameter is the party identifier that can be used as the partyRef on the partyAdded APIs to add the party to a trade object (consignment or transport equipment).

Business Partners12a.png

Now we will show how the party identifier can be used to add the party to a consignment (or transport equipment). In our example, we will assume that the carrier already has a consignment created, so we will just add the shipper to the existing consignment, using the party identifier that the carrier specified for the business partnership. We use the POST ​...​/consignments​/partyAdded - Consignment visibility added (E001) API to add the shipper by partyRef.

Business Partners13b.png

From the shipper, we can now see the consignment that the carrier created, and we see that the shipper has been added with the role of transport service buyer. This also means that any business partner rules, that the shipper (TSB) created, that match incoming events will be executed and the business partners will be added to the consignment with the specified party role from the rule.

Business Partners15d.png

Also notice the Created By filter on the UI. This additional search option will display a list of organization names that have created consignments that your organization has visibility to see. You can use the filter to select specific organization names and view only those consignments.

Business Partners17d.png