Elements Data Flow
The following is an overview of the data flow between Elements and your web application and includes some best practices for data ownership.
Ownership of data
While the Elements application can operate in isolation and used by users to purchase labels within a user session, some key points of integration can provide greater benefit to your application and the general user experience. Some of these cases can include the following:
Saving the tracking number and shipment status
After purchasing a shipping label, you may want to save and display the fulfillment status and/or tracking number of the shipment in your interface. Both of these properties are available in the LABEL_PURCHASED event (see docs here: Shipping Elements Events). This event includes some crucial information such as:
- Estimated time of arrival
- Tracking number
- Total cost
- Shipping Label link
- Packing Slip URL
- Status
While users can view all of this information in Elements, you may choose to take the data from the event callback function, save on your server and display it in your application. This could save the user an extra step of opening elements to view this information or provide the information for internal usage such as reporting or analytics.
Note
If you are relying on elements to provide access to tracking information or links to download labels in a session after the label was created, save and pass the order object_id into the OrderDetails object of the labelPurchase() function to load the order. See below for more information.
Persisting label creation edits across Shipping Elements sessions
On the initial render of Shipping Elements, you can choose to load an existing order or create a new order and this logic is dictated by the object_id passed in through the OrderDetails object to the labelPurchase function. This object_id is a unique representation of an order in our system. These are the same orders that a user will see if logging into the Shippo web application and are necessary to save and persist a user's changes/selections related to the shipping label.
When an order is created in elements, an ORDER_CREATED event is emitted (see docs here: Shipping Elements Events). It is recommended to save the order_id and associate it with the order in your web application. It can then be passed as the object_id to labelPurchase for future sessions to maintain the edits and state of the order. This is particularly important for the following cases:
- User has made some edits to the label, but has not yet purchased
- The user has purchased a label and is looking to view tracking information or download the label/packing slip
If an object_id is not passed, Shipping Elements will assume you want to create a new shipping label. This may also represent duplicate orders in the Shippo web application for a singular order within your web application.
Below is a diagram of the data flow of order information through events:
