Purchase Label Element

The Purchase Label Element is a versatile UI component designed to streamline the process of creating and purchasing shipping labels. It provides a comprehensive solution that includes:

Before you get started

Before implementing the Purchase Label Element, there are important prerequisites and requirements to consider.

Shipping Carriers

Before your users can start shipping with the Purchase Label Element, they must create ShipEngine carrier accounts or have pre-existing carrier accounts registered with ShipEngine. Using the Onboarding Element will allow your users to register new ShipEngine carrier accounts easily. Check out the Onboarding Element to learn more about registering ShipEngine carriers.

If your users already have pre-configured carrier accounts, check out the External Carriers Element to learn more about linking external carriers to use in the Purchase Label Element.

Shipments

The Shipment object is used throughout the label purchase process. Shipments are the source of truth the Purchase Label Element uses to read and write the information necessary to purchase shipping labels. Shipping information like ship-to and ship-from addresses, package dimensions, and insurance are just some of the entities stored in a shipment object. A complete understanding of shipments is not required to use the Purchase Label Element, but it can be beneficial when debugging. Check out the full shipment documentation for more details.

Ship From locations

To create shipments, you must define the address your shipment is originating from (home, office, warehouse, or anywhere with a valid address). This can be done by either setting the desired ship-from address or passing a warehouse ID in the request body when creating a shipment. It's important to note that a ship-from address or a valid warehouse ID is required to create a new shipment.

When providing a ship-from address, keep the following in mind:

Example Ship From Address

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
const shipFromAddresses = [
  {
    name: "The Mayor's Office",
    isDefault: true,
    originAddress: {
      addressLine1: '301 W 2nd St',
      cityLocality: 'Austin',
      countryCode: 'US',
      name: 'Kirk Watson',
      phone: '(512) 974-2000',
      postalCode: '78701',
      stateProvince: 'TX',
    },
    returnAddress: {
      addressLine1: '4301 Bull Creek Rd',
      cityLocality: 'Austin',
      countryCode: 'US',
      name: 'Al Ko',
      phone: '(512) 886-4006',
      postalCode: '78731',
      stateProvince: 'TX',
    },
  },
];

Warehouses

A warehouse is a colloquial term ShipEngine uses to refer to saved ship-from locations. Each new warehouse created comes with a unique ID used to reference a saved ship-from address during the creation of a shipment and throughout shipment configuration within the element. Setting the warehouse_id field to a valid warehouse ID in the shipment creation request body will create a new shipment with that warehouse's origin and return address. To learn more about warehouses, check out the full warehouse documentation. If you plan on using the Onboarding Element, a warehouse will automatically be created for your users.

Create a Purchase Label Element

While implementing the Purchase Label Element it is important to consider how the Element will fit into your platform and how you plan on hydrating the Element with Shipment data. It is also important to decide how your platform will manage the ship from locations used inside of the the Purchase Label Element.

To hydrate the Purchase Label Element with shipment data, you can provide a shipmentId, externalShipmentId, or salesOrderId. The Element will create an unassociated one-off shipment if you do not provide an entity ID.

If you plan on using Sales Orders to power the Purchase Label Element, it's important to note that while ShipEngine Sales Orders have a one-to-many relationship with shipments, the Purchase Label Element can handle only one shipment at a time. We recommend limiting one shipment to each Sales Order.

The Purchase Label Element will check for any corresponding pending shipments, indicating that these shipments are eligible for purchase. The Element will create a new shipment if no shipments are associated with the provided salesOrderId.

Check out the Shipment Summary Element for more information about viewing shipments with active or voided labels.

During the one-off Shipment creation process, the Element will first look for any addresses passed to the Element via the shipFromAddresses prop or argument. If none are present, the Element will use the ShipEngine warehouse associated with the ID passed to the warehouseID prop or argument. If all else fails, the Element will use a ShipEngine warehouse saved on the user's ShipEngine account.

If you decided on passing in you own ship-from addresses to the Purchase Label Element make sure that the addresses are of the correct type.

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
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
import { PurchaseLabel, ElementsProvider } from '@shipengine/elements';
import { themeConfig } from '../themeConfig';
import { shipFromAddresses } from '../shipFromAddresses'

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

const Foo = ({ shipments }) => {
  const [selectedShipment, setSelectedShipment] = useState();

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

  return (
    <ElementsProvider
      getToken={getToken}
      themeConfig={themeConfig}
      onError={handleError}
      features={{
        globalFeatures: {
          enabledShipEngineCarriers: ['ups', 'stamps_com'],
          enabledExternalCarriers: [
            'apc',
            'asendia',
            'better_trucks',
            'courierpost',
            'dpd',
            'seko',
            'ups',
            'yodel',
          ],
          poweredByShipEngine: true
        },
        purchaselabelFeatures: {
          rateForm: { enableFunding: true },
          shipmentForm: { shippingPresets: true },
        }
      }}
    >
      <ul>
        {shipments.map((shipment) => (
          <li>
            <button onClick={() => setSelectedShipment(shipment)}>
              Order #{shipment.`shipmentId`}
            </button>
          </li>
        ))}
      </ul>

      {selectedShipment && (
        <PurchaseLabel.Element
          onLabelCreateSuccess={() => {
            console.log('Success!');
          }}
          printLabelLayout={
            'letter' // '4x6'
          }
          shipmentId={shipmentId}
          shipFromAddresses={shipFromAddresses}
        />
      )}
    </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
26
27
28
29
30
31
32
33
34
35
36
37
// 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: {
      globalFeatures: {
        enabledShipEngineCarriers: ['ups', 'stamps_com'],
        enabledExternalCarriers: [
          'apc',
          'asendia',
          'better_trucks',
          'courierpost',
          'dpd',
          'seko',
          'ups',
          'yodel',
        ],
      },
      purchaselabelFeatures: {
        rateForm: { enableFunding: true },
        shipmentForm: { shippingPresets: true },
      }
    }
  }
);

const purchaseLabel = elements.create('purchaseLabel', {
  onLabelCreateSuccess: () => console.log('Success!'),
  printLabelLayout: {
    'letter' // '4x6'
  },
  shipmentId: "se-103889776",
  shipFromAddresses
});

Purchase Label Features

Features are optional configuration keys used to customize the Purchase Label experience.

To disable GlobalPost rates from appearing in the PurchaseLabel element, format the disabledShippingServices property as follows. Since GlobalPost rates may appear on both usps and stamps_com carriers, both carriers are included in the property:

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "disabledShippingServices": {
    "usps" : [
      "globalpost_economy",
      "globalpost_priority",
      "gp_plus" ],
    "stamps_com" : [
      "globalpost_economy",
      "globalpost_priority",
      "gp_plus"
    ]
  }
}

Shipment Form Features

Rate Form Features

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.

1