Site Logo

Connect External Carrier Element

The Connect External Carrier Element allows users to connect their own existing external carrier account.

For more information about External Carrier Connections, refer to the full carrier connection documentation.

To view and manage previously connected accounts, and to add additional external carrier accounts, we recommend instantiating the Manage External Carriers Element.

Configuring Carriers

By providing a value to the carrierName prop, the Connect External Carrier Element will populate a form with the required fields relevant to the carrier specified.

If carrierName is not provided, users will be able to select a carrier to connect from a list of carriers specified within the globalFeatures.enabledExternalCarriers array within the features prop.

For an in depth overview of the global features object, please review the Configuring Elements Features step in either the ElementsProvider or the Elements SDK guides.

React Component

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
import { ConnectExternalCarrier, ElementsProvider } from '@shipengine/elements';
import { themeConfig } from '../themeConfig';


const tokenPath = '/path/to/token/endpoint';


const Foo = () => {
  const getToken = useCallback(() => {
    return fetch(tokenPath).then((res) => res.text());
  }, []);


  return (
    <ElementsProvider
      getToken={getToken}
      themeConfig={themeConfig}
      onError={handleError}
      features={{
        enabledShipEngineCarriers: [
          'stamps_com',
          'dhl_express_worldwide'
        ]
        // The list of external carriers that are available to be activated
        enabledExternalCarriers: [
          'apc',
          'asendia',
          'better_trucks',
          'courierpost',
          'dpd',
          'seko',
          'ups',
          'yodel',
        ],
      }}
    >
      <ConnectExternalCarrier.Element
        carrierName="ups"
        onCarrierConnected={() => console.log('carrier successfully connected')}
      />
    </ElementsProvider>
  );
};

SDK

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
// Creates a new instance of the Elements SDK.
const elements = new ElementsSDK(getToken, {
  onError: (err: Error) => console.error(err),
  themeConfig: themeConfig,
  locale: 'en-US',
  features: {
    enabledShipEngineCarriers: ['stamps_com', 'dhl_express_worldwide'],
    // The list of external carriers that are available to be activated
    enabledExternalCarriers: [
      'apc',
      'asendia',
      'better_trucks',
      'courierpost',
      'dpd',
      'seko',
      'ups',
      'yodel',
    ],
  },
});


const connectExternalCarrier = elements.create('connectExternalCarrier', {
  carrierName: 'ups',
  onCarrierConnected: () => console.log('carrier successfully connected'),
});
Args/PropsDescription
carrierNamestring, optional The carrier name to show the connection form for (ie. ups, usps, fedex, etc.). If no carrier is provided, the user may select from a list of carriers specified in the enabledExternalCarriers array.
onCancelfunction, optional An optional callback function that will be invoked when a carrierName was provided and the form is cancelled. Otherwise the user will again be presented with the list of available carriers to connect.
onCarrierConnectedfunction, optional An optional callback function to be invoked after the successful connection of a carrier account.