The following is an overview of the data flow between Elements and your web application and includes some best practices for data ownership.
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:
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
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.
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.
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
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: