Site Logo

🎉 ShipEngine is becoming ShipStation API 🎉

Over the next few months you'll notice the ShipEngine website, documentation portal, and dashboard being rebranded as ShipStation API. For our ShipEngine customers, you don't need to take any action or change any of your integrations in any way. All endpoints will remain the same and continue to function as they always have.

To learn more about what's coming, review our New ShipStation API page.

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.

DANGER: If you do not pass a value to carrierName and exclude the globalFeatures.enabledExternalCarriers property, or set the value to an empty array without including any supported carrier codes, users will not be able to view and connect External Carriers.

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.