Choosing Business Cases/User Stories

To build the desired shipping system using Shippo's API, integrating partners will need to choose from a list of user stories. These user stories represent different business cases, which are the various scenarios that can occur when fulfilling orders. By selecting the appropriate user stories, the integrating partner will define the work that needs to be done to build the desired shipping system.

For example, the integrating partner may need to handle scenarios such as printing shipping labels, generating tracking numbers, processing returns, handling multiple carriers and shipping options, and integrating with customs clearance. By selecting the appropriate user stories, the integrating partner can ensure that the shipping system they build is customized to meet their specific business needs. Shippo's API offers a wide range of user stories to choose from, making it easy to build a flexible and customizable shipping system.

User Stories to be Selected

Shipments & Transactions

The following user stories cover the Shipments and Transactions endpoints using Shippo's API:

These user stories cover the functionalities that are associated with fetching carrier rates, rate shopping, and purchasing labels using Shippo's API. By selecting the appropriate user stories, integrating partners can ensure that their e-commerce platforms can compare rates and purchase labels seamlessly.

As a Shipper, I want to compare rates and then purchase a label
As a Shipper, I want to purchase a label in one step
As a Shipper, I want to display rates to a consumer to choose a rate and then purchase a label
As a Shipper, I want to be able to view the purchased label
As a Shipper, I want to be able to print the purchased label
As a Shipper, I want to be able to refund the purchased label

Customs Declarations

Customs declarations are relevant information, including one or multiple customs items, you need to provide for customs clearance for your cross-border shipments. The following user stories cover customs declarations using Shippo's API:

As a Shipper, I want to include customs data included in my shipment creation requests
As a Shipper, I want to print commercial invoices to include with my cross-border packages

By selecting the appropriate user stories, integrating partners can ensure that their e-commerce platforms can include customs data in shipment creation requests and properly document cross-border packages. This functionality is important for proper customs clearance and acceptance

Multi-Parcel Shipments

Multi-parcel shipments are shipments with multiple packages sent to the same destination that can be grouped together in a multi-piece shipment to save money. The following user stories cover multi-parcel shipments:

As a Shipper, I want to be able to create a multi-parcel shipment and receive shipping rates
As a Shipper, I want to be able to purchase a label using the multi-parcel shipment's rates
As a Shipper, I want to be able to view the purchased label
As a Shipper, I want to be able to print the purchased label
As a Shipper, I want to be able to refund the purchased labels

By selecting the appropriate user stories, integrating partners can ensure that their e-commerce platforms can create multi-parcel shipments, receive shipping rates, purchase labels, and view and print purchased labels. This functionality is important for shipments that require multiple packages sent to the same destination. For more information on multi-parcel shipments, please visit the following link: https://docs.goshippo.com/docs/shipments/multipieceshipment/

Refunding Labels

Refunding labels is an important process that allows shippers to return money spent on unused labels. However, there are certain best practices that should be followed when refunding labels, such as checking that a label has not been used before issuing a refund, pending refunds to ensure a label has not been printed and will be used, and blocking the reprinting of a refunded label. The following user stories cover label refunds:

As a Shipper, I want to be able to check the status of a label before refunding
As a Shipper, I want to be able to hold a refund request before distributing funds
As a Shipper, I want to be able to block reprinting a label that has a refund request
As a Shipper, I want to be able to check the status of a refund request

By selecting the appropriate user stories, integrating partners can ensure that they are able to properly manage refunds and avoid issues such as refunding a label that has already been used. For more information on label refunds, please visit the following link: https://docs.goshippo.com/docs/billing_and_invoices/refundinglabels/

Tracking Shipments

The Shippo Tracking API allows you to track shipments across all carriers with normalized data, full tracking history and real-time updates. When combined with webhooks, you will get push-style notifications anytime a tracking update occurs from the carrier. This powerful combination allows you to always know what the latest tracking information is across all of your shipments and if a recipient may need to take action to retrieve their shipment in a single service.

Associated user stories should include:

As a (Shipper) I want to be able to receive automatic tracking updates on a shipment
As a (Shipper) I want to be able to request the tracking status of a shipment
As a (Shipper) I want to be able to get notifications when a shipment is delivered
As a (Shipper) I want to be able to receive alerts for shipping exceptions

Webhooks

Webhooks are a part of the Shippo integration that will allow you to receive automatic updates when subscribed events occur. Much like other webhooks, you will request subscription notifications are sent to specific endpoints. This is useful for sending shipping updates to consumers, monitoring for undeliverable packages, transaction administration, and many other use cases.

Webhook	Use
Transaction Created	Sent whenever a transaction is created in your account. The POST request body will contain a JSON of the Transaction object that was created.
Transaction Updated	Sent whenever a transaction is updated in your account. The POST request body will contain a JSON of the Transaction object that was updated.
Track Updated	For tracking status updates. The POST request body will contain a JSON of the Tracking object. If you are interested in the types of events returned within the track_updated field, please view more details here.
Batch Created	For creating the Batch object that contain Batch Shipments. This process is done asynchronously, so first you’d get an empty Batch object back, then Batch Shipments will be created in the background.
Batch Purchased	For purchasing Batch Shipments through the Batch endpoint. This request is done asynchronously as well. Once purchases are complete, you will be able to download a merged PDF containing up to 100 labels per file.

Associated user stories should include:

As a (Shipper) I want to be able to subscribe to a webhook and specify the update
As a (Shipper) I want to be able to unsubscribe from a webhook
As a (Shipper) I want to be subscribed to a webhook automatically when ___ occurs

Batch Shipments

Batch shipments allow the ability to create and purchase many shipments in one API call. The following user stories cover batch shipments using Shippo's API:

By selecting the appropriate user stories, integrating partners can ensure that their e-commerce platforms can create and purchase many shipments in one API call, which is useful for shippers that work in batches at the end of or several times a day. Batching is a flexible process that can purchase many shipments from different carriers or be used to purchase an array of shipments for a specified service level and carrier. For more information on batch shipments, please visit the following link: https://docs.goshippo.com/docs/shipments/batchlabelcreation/

As a Shipper, I want to be able to purchase a batch
As a Shipper, I want to be able to add a shipment to a batch
As a Shipper, I want to be able to remove a shipment from a batch
As a Shipper, I want to be able to get updated when an exception occurs
As a Shipper, I want to be able to handle exceptions that occur during batch processing
As a Shipper, I want to be able to notify specific recipients when a batch is purchased
As a Shipper, I want to be able to retrieve the details of a batch

Carrier Integration

The following user stories cover the integration of carriers using Shippo's API:

As a Shipper, I want to be able to create a new carrier account that I will share with my merchants
As a Shipper, I want to be able to create a new BYOA carrier
As a Shipper, I want to be able to retrieve the details of an individual carrier account
As a Shipper, I want to be able to update a BYOA carrier account
As a Shipper, I want rates that are cost-effective for my business to deliver the sold product to the shipper on or before the date I told them at checkout
As a Platform, I want to be able to list a merchant’s carrier accounts
As a Platform, I want to be able to add a carrier account to a merchant
As a Platform, I want to be able to disable a merchant’s carrier accounts
As a Platform, I want to be able to remove a merchant’s carrier account
As a Platform, I want to be able to auto-provision a merchant’s carrier account for carrier
As a Platform, I want to be able to provide detailed billing information to my merchants

Note that the "list all carrier accounts" user story is not applicable for the platform, as the platform only has access to the carrier accounts of their merchants, not all carrier accounts.

Carrier Manifests and Scan Forms

Carrier Manifests are close-outs of shipping labels of a certain day. Daily manifests are required by some carriers and are meant to be used for proper billing and acceptance of shipments. The following user stories cover Carrier Manifests and Scan Forms using Shippo's API:

By selecting the appropriate user stories, integrating partners can ensure that their e-commerce platforms can create, retrieve, and list shipping manifests using Shippo's SCAN Form and Manifest API. This functionality is important for proper billing and acceptance of shipments with some carriers. For more information on Carrier Manifests and Scan Forms, please visit the following link: https://docs.goshippo.com/docs/manifests_and_pickups/manifestandscanforms/

As a Shipper, I want to be able to create a shipping manifest
As a Shipper, I want to be able to retrieve a shipping manifest
As a Shipper, I want to be able to list all manifests

Address Management

Shippo's API provides functionalities for validating and storing addresses, which can be useful for e-commerce integrations. The following user stories cover address management using Shippo's API:

By selecting the appropriate user stories, integrating partners can ensure that their e-commerce platforms can validate and store addresses, which can prevent complications later in the checkout process. These functionalities can also provide value for use cases such as return and shipping addresses that do not change or a customer address book for recurring transactions.

As a Shipper, I want to be able to validate and store an address at a specific point
As a Shipper, I want to be able to decide what to do when an address fails validation
As a Shipper, I want to be able to retrieve a stored address object ID for a specific use case
As a Shipper, I want to be able to turn on and off the ability to bypass address validation
As a Shipper, I want to be able to override failed address validation
As a Shipper, I want to be able to update and store a new address with validation
As a Shipper, I want to be able to update and store a new address without validation

Parcel Templates

Parcel templates are predefined package parameters that can be used qto streamline the shipping process. The following user stories cover parcel templates using Shippo's API:

By selecting the appropriate user stories, integrating partners can ensure that their e-commerce platforms can use predefined package parameters to streamline the shipment process. These functionalities can be useful for situations where a merchant always ships a subscription in the same sized box, or a warehouse only uses a few box sizes, making rating and shipping easier. For more information on parcel templates, please visit the following link: https://docs.goshippo.com/shippoapi/public-api/#tag/User-Parcel-Templates

As a Shipper, I want to be able to store a parcel template
As a Shipper, I want to be able to delete a stored parcel template
As a Shipper, I want to be able to update a stored parcel template
As a Shipper, I want to be able to retrieve and apply a parcel template when needed
As a Shipper, I want to be able to retrieve a list of parcel templates for my account

Orders

The orders endpoint allows you to load orders from your system to the Shippo dashboard and to create, retrieve, list, and manage orders programmatically. You can also retrieve shipping rates, purchase labels, and track shipments for each order.

This functionality https://docs.goshippo.com/docs/oauth_integrations/webappordersync/ will only be needed if you are not building a native shipping user interface. Associated user stories should include:

As a (Shipper) I want to have my orders viewable in the Shippo dashboard
As a (Shipper) I want to have my orders update when changes or canceled in the Shippo dashboard
As a (Shipper) I want to have my shipping information viewable in my ____ dashboard

Special Shipments

Special shipments can include a variety of situations like dry ice, alcohol, or lightly regulated hazardous materials. In general, you will use the user stories and API functions for other shipments when handling these use cases but need to include additional data based on the situation. Because these requirements can change based on carrier, location, and other factors, be sure to discuss your use cases for these situations with your Shippo team.

Associated user stories should include:

As a (Shipper) I want to include needed data when creating a special shipment
As a (Shipper) I want to update needed data when creating a special shipment

Returns

Returns have a variety of use cases that the Shippo API can be used to address. To simplify the matter it is best to define what the types of returns are. Scan Based Returns - These are return labels a shipper is not charged for unless it is used by the recipient to ship a package. The carriers require these labels be associated with an original outbound label and will bill for the size and weight of that package. A great use case for these labels is when a recipient is returning an item for a like item such as trading in a cell phone. Shipper Provided Return Labels - These are labels that are generated by a business for a customer to return an item and not provided in the original packaging. From a technical perspective, these labels are the same as a regular outbound label. The business will most likely provide a PDF or the URL of the label for the customer to print out and return the item. Stand Alone Return Labels - These are labels provided to a customer to return an item where no original label may have been purchased through Shippo. This may be situations like warranty claims, returns portals, collectible evaluation, and trade ins. From a technical perspective, these labels are the same as a regular outbound label. The business will most likely provide a PDF or the URL of the label for the customer to print out and return the item.

Associated user stories should include:

As a (Shipper) I want to be able to include a scan based return label with an outbound shipment
As a (Shipper) I want to be able to send a new outbound label to process a return
As a (Shipper) I want to be able to send a return label to a (customer) related to an original Shippo label purchase

Managing Payment Methods

Payment methods are typically a card or ACH data kept on file to collect payment for labels and label fees as well as refund labels. If you are building a native UI you will need to build a method for these updates. If you are using Shippos UI you will need to build a method to redirect users to the screens in Shippos UI to perform updates.

It is important to note there is not an API for managing payment methods at this time. White label integrations will manage payments through their Shippo account and Gray Label will require using OAuth to access the Shippo Web App.

Associated user stories should include:

As a (Shipper) I want to add a new payment method
As a (Shipper) I want to delete a payment method
As a (Shipper) I want to update a payment method

Invoicing

If you are building your own UI you will want to have a method of sending customers invoices at the desired interval(s) so they can keep an account of their shipping expenses.

Associated user stories should include:

As a (Shipper) I want to get a daily record of my shipping expenses
As a (Shipper) I want to get a weekly record of my shipping expenses
As a (Shipper) I want to get a monthly record of my shipping expenses
As a (Shipper) I want to get a record of my shipping expenses when a payment is made

Reporting

Your users will often want to receive reporting on their shipping so they can improve their business practices. Using the data in your system and shipping data from Shippo you can provide them with valuable information to help them succeed.

Examples of Reports requested by Users

Shipment analysis trends based on time (day, week, month, hour)
Shipment analysis by carrier and service level for cost, performance, and other factors
Shipment analysis by costs related to product, destination, origin, etc.

Associated user stories should include:

As a (Shipper) I want to get a daily report of my shipping __
As a (Shipper) I want to get a weekly report of my shipping __
As a (Shipper) I want to get a monthly report of my shipping __