medusa-fulfillment-shippo





ℹ️ Requires Medusa ^1.3.5
Shippo fulfillment provider for Medusa Commerce.
Provides fulfillment options using carrier service levels and user created service groups that can be used to create shipping options for profiles and regions.
Rates at checkout optimized with a first-fit-decreasing (FFD) bin packing algorithm.
Fulfillments create orders in shippo.
Supports returns, exchanges, and claims.
Public interface for rapid custom integration. Reference | Quick Reference
Eventbus payloading instead of arbitrary data assumption and storage.
Table of Contents
- Getting Started
- Orders
- Packing Slips
- Returns
- Swaps
- Claims
- Rates at Checkout
- Webhooks
- Public Interface
- Events
- Shippo Node Client
- Release Policy
- Limitations
- Resources
Getting started
Install:
Copy to clipboard> npm i medusa-fulfillment-shippo
Add to medusa-config.js
Orders
Creating an order fulfillment makes a new order in shippo. An event is emitted with the response data and related internal ids.
Create a Subscriber to access the data.
Event:
Copy to clipboardshippo.order_created
Retrieve
See references for all methods
Packing Slips
Retrieve
See references for all methods
Returns
Request
Invoked when Request a Return
hasCopy to clipboardreturn_shipping
Copy to clipboardprovider: shippo
Attempts fetching an existing return label from shippo.
Event:
Copy to clipboardshippo.return_requested
Swaps
Create
Attempts fetching an existing return label from shippo.
Event:
Copy to clipboardshippo.swap_created
Fulfillment
Invoked when Create a Swap Fulfillment
hasCopy to clipboardshipping_option
Copy to clipboardprovider: shippo
Creates an order in shippo.
Event:
Copy to clipboardshippo.replace_order_created
Claims
Refund
Invoked when Create a Claim has
andCopy to clipboardtype: refund
hasCopy to clipboardreturn_shipping
Copy to clipboardprovider: shippo
Attempts fetching an existing return label from shippo.
Event:
Copy to clipboardshippo.claim_refund_created
Replace
Invoked when Create a Claim has
andCopy to clipboardtype: replace
hasCopy to clipboardreturn_shipping
Copy to clipboardprovider: shippo
Attempts fetching an existing return label from shippo.
Event:
Copy to clipboardshippo.claim_replace_created
Fulfillment
Invoked when Create a Claim Fulfillment
hasCopy to clipboardshipping_option
Copy to clipboardprovider: shippo
Creates an order in shippo.
Event:
Copy to clipboardshippo.replace_order_created
Rates at Checkout
Provide customers with accurate shipping rates at checkout to reduce over and under charges. This plugin implements a first-fit-decreasing bin packing algorithm to choose an appropriate parcel for the items in a cart. Follow this guide to get setup and then optimize.
Setup Shipping Options in Shippo App
Lets assume shipping from Canada to customers in Canada and USA via “Standard” and “Express” options
This would require setting up 4 shipping options in Shippo (<https://apps.goshippo.com/settings/rates-at-checkout>)
- Standard Shipping Canada
- Express Shipping Canada
- Standard Shipping USA
- Express Shiping USA
Set each shipping option to “Live rate” and assign service(s) to them
For example:
- Express Shipping Canada: Canada Post XpressPost
- Express Shipping USA: Canada Post XpressPost USA
- …
For more in-depth details see https://support.goshippo.com/hc/en-us/articles/4403207559963
Assign Shipping Options to Regions in Medusa
Create shipping options for regions as usual
Setup parcel templates
Create package templates in the Shippo app settings
To get most optimal results, it is recommended to create package templates for all your shipping boxes.
Verify product dimensions and weight
In your medusa store, make sure products have correct values for length, width, height, weight
During Checkout
Retrieve shipping options for cart as usual and any
options belonging toCopy to clipboardprice_type: calculated
will haveCopy to clipboardprovider: shippo
.Copy to clipboardamount: Number
Rates calculate only if cart has shipping address and items
HTTP:
Service:
Add to Cart
Add a Shipping Method and if
hasCopy to clipboardshipping_option
the rate will be saved to theCopy to clipboardprice_type: calculated
Copy to clipboardshipping_method
HTTP:
Help, adding a shipping method to cart throws an error
This is an issue with medusa-admin. Examine line 85
Copy to clipboardadmin/src/domain/settings/regions/new-shipping.tsx
Options with
will not pass throughCopy to clipboardprice_type: flat_rate
Copy to clipboardfulFillmentProviderService.calculatePrice()
medusa-admin is still early phase software.
Workaround it, use the REST api directly, or patch the issue for now
Possible interim solution:
Webhooks
Caution
Incoming HTTP requests from Shippo to webhook endpoints lack authentication. No secret token, no signature in the request header, no bearer, nothing.
Before enabling webhooks, understand the risks of an open and insecure HTTP endpoint that consumes data, and how to mitigate this. Please DO NOT use this without SSL/TLS. Whitelisting shippo IP's is a good idea. There are also intermediary third party services such as pipedream and hookdeck that can be used to relay requests.
You will also need to self generate a token and add it as a url query param. Ya I know… but it's better than nothing and it is encrypted over HTTPS
The flow at the code level is:
- Webhook receives POST data
- URL query token is verified
- The request json gets verified by fetching the same object directly from shippo API, following these steps:
- Request body contains json claiming to be a shippo object.
- Ok, but lets fetch this object directly from Shippo's API
- If the fetch resolves to the object requested, then use that data instead of the untrusted input
- Otherwise throw a HTTP 500 and do nothing
Setup
In
addCopy to clipboard.env
Copy to clipboardSHIPPO_WEBHOOK_SECRET=some_secret_string
Add to
Copy to clipboardmedusa-config.js
Endpoints
Hooks need to be setup in Shippo app settings
transaction_created:
Copy to clipboard/hooks/shippo/transaction?token=SHIPPO_WEBHOOK_SECRET
transaction_updated:
Copy to clipboard/hooks/shippo/transaction?token=SHIPPO_WEBHOOK_SECRET
track_updated:
Copy to clipboard/hooks/shippo/track?token=SHIPPO_WEBHOOK_SECRET
Then send a sample. If everything is good you will see this in console:
This is the expected behaviour because the data could not be verified. Since it is a sample, when the plugin tried to verify the transaction by requesting the same object back directly from shippo api, it did not exist. It will NOT use input data beyond making the verification, so it gets rejected.
Test Mode
Test mode bypasses input authenticity verification, i.e. it will use the untrusted input data instead of requesting the same data back from shippo.
This allows testing using data that does not exist in shippo.
To enable, set
inCopy to clipboardwebhook_test_mode: true
plugin options.Copy to clipboardmedusa-config.js
Running in test mode is a security risk, enable only for testing purposes.
transaction_created
Copy to clipboard/hooks/shippo/transaction?token=SHIPPO_WEBHOOK_SECRET
Receives shippo transaction object when label purchased
- Updates fulfillment to “shipped”
- Adds tracking number and link to fulfillment
Events
Copy to clipboardshippo.transaction_created.shipment
Copy to clipboardshippo.transaction_created.return_label
transaction_updated
Copy to clipboard/hooks/shippo/transaction?token=SHIPPO_WEBHOOK_SECRET
Receives shippo transaction object when transaction updated
Events
Copy to clipboardshippo.transaction_updated.payload
track_updated
Copy to clipboard/hooks/shippo/track?token=SHIPPO_WEBHOOK_SECRET
Events
Copy to clipboardshippo.track_updated.payload
Public Interface
References the declared public interface for client consumption, the semver "Declared Public API"
Although there is nothing stopping you from accessing and using public methods behind the interface, be aware that those implementation details can and will change. The purpose of the interface is semver compliant stability.
Getting Started
Dependency inject
as you would with any other serviceCopy to clipboardshippoService
For guide, see Using Custom Service
account.address()
Fetch default sender address
Return
Copy to clipboardPromise.<object>
Example
order.fetch(id)
Fetch an order from shippo
Parameters
Name | Type | Description |
---|---|---|
id |
| The object_id for an order |
Return
Copy to clipboardPromise.<object>
Example
order.with([entity]).fetch(id)
Fetch a shippo order with a related entity.
Parameters
Name | Type | Description |
---|---|---|
id |
| The object_id for an order |
entity |
| The entity to attach |
Supported Entities
Copy to clipboardfulfillment
Return
Copy to clipboardPromise.<object>
Example
order.fetchBy([entity, id])
Fetch a shippo order using the id of a related entity
Parameters
Copy to clipboard@param {[entity: string, id: string>]}
Name | Type | Description |
---|---|---|
entity |
| The entity type to fetch order by |
id |
| Id of the entity |
Supported Entities
Copy to clipboardfulfillment
Copy to clipboardlocal_order
Copy to clipboardclaim
Copy to clipboardswap
Return
Copy to clipboardPromise.<object|object[]>
Example
package.for([entity, id]).fetch()
Bin pack items to determine best fit parcel using package templates from shippo account
Will return full output from binpacker, including locus. The first array member is best fit
See also: override package templates
Parameters
Copy to clipboard@param {[entity: string, id: string>]}
Name | Type | Description | |
---|---|---|---|
entity |
| Entity type | |
id | items |
| The id of {[entity]} or array of items |
Supported Entities
Copy to clipboardcart
Copy to clipboardlocal_order
Copy to clipboardfulfillment
Copy to clipboardline_items
Return
Copy to clipboardPromise.<object[]>
Example
Override Parcel Templates
Copy to clipboardpackage.set("boxes", [...packages])
packingslip.fetch(id)
Fetch the packingslip for shippo order
Parameters
Name | Type | Description |
---|---|---|
id |
| The object_id of the order to get packingslip for |
Return
Copy to clipboardPromise.<object>
Example
packingslip.with([entity]).fetch(id)
Fetch the packingslip for shippo order with a related entity.
Parameters
Name | Type | Description |
---|---|---|
id |
| The object_id of the order to get packingslip for |
entity |
| The entity to attach |
Supported Entities
Copy to clipboardfulfillment
Return
Copy to clipboardPromise.<object>
Example
packingslip.fetchBy([entity, id])
Fetch the packing slip for a shippo order, using the id of a related entity
Parameters
Copy to clipboard@param {[entity: string, id: string>]}
Name | Type | Description |
---|---|---|
entity |
| The entity type to fetch packingslip by |
id |
| Id of the entity |
Supported Entities
Copy to clipboardfulfillment
Copy to clipboardlocal_order
Copy to clipboardclaim
Copy to clipboardswap
Return
Copy to clipboardPromise.<object|object[]>
Example
track.fetch(carrier_enum, track_num)
Fetch a tracking status object
Parameters
Name | Type | Description |
---|---|---|
carrier_enum |
| The carrier enum token |
track_num |
| The tracking number |
Return
Copy to clipboardPromise.<object>
Example
track.fetchBy([entity, id])
Fetch a tracking status object using id of related entity
Copy to clipboard@param {[entity: string, id: string>]}
Name | Type | Description |
---|---|---|
entity |
| The entity type to fetch tracking status by |
id |
| Id of the entity |
Supported Entities
Copy to clipboardfulfillment
Return
Copy to clipboardPromise.<object>
Example
transaction.fetch(id)
Fetch a transaction object from shippo.
To fetch an extended version with additional fields, use
Copy to clipboardtransaction.fetch(id, { type: extended})
Name | Type | Description |
---|---|---|
id |
| The object_id for transaction |
Return
Copy to clipboardPromise.<object>
Example
transaction.fetchBy([entity, id])
Fetch a transaction using the id of a related entity
Parameters
Copy to clipboard@param {[entity: string, id: string>]}
Name | Type | Description |
---|---|---|
entity |
| The entity type to fetch transaction by |
id |
| Id of the entity |
Supported Entities
Copy to clipboardfulfillment
Copy to clipboardlocal_order
Copy to clipboardclaim
Copy to clipboardswap
Return
Copy to clipboardPromise.<object|object[]>
Example
Misc
is([entity, id], attr).fetch()
Client
(forked)Copy to clipboardshippo-node-client
find(entity).for([entity, id])
Quick Reference
Account
Order
Package
Packingslip
Track
Transaction
Client
Find
Events
List of all events, their triggers, and expected payload for handlers
Subscribe to events to perform additional operations
These events only emit if the action pertains to
Copy to clipboardprovider: shippo
shippo.order_created
Triggered when a new fulfillment creates a shippo order.
Payload
shippo.return_requested
Triggered when a return is requested
If the return
hasCopy to clipboardShippingMethod
it attempts to find an existing return label in shippo.Copy to clipboardprovider: shippo
Payload
shippo.swap_created
Triggered when a swap is created
If return
hasCopy to clipboardShippingMethod
it attempts to find an existing return label in shippo.Copy to clipboardprovider: shippo
Payload
shippo.replace_order_created
If the
hasCopy to clipboardShippingMethod
a shippo order is createdCopy to clipboardprovider: shippo
Payload
shippo.claim_refund_created
Triggered when a
claim is createdCopy to clipboardtype: refund
If return
hasCopy to clipboardShippingMethod
, it attempts to find an existing return label in shippoCopy to clipboardprovider: shippo
Payload
shippo.claim_replace_created
Triggered when a
claim is createdCopy to clipboardtype: replace
If return
hasCopy to clipboardShippingMethod
, it attempts to find an existing return label in shippoCopy to clipboardprovider: shippo
Payload
shippo.transaction_created.shipment
Triggered when the
webhook updates aCopy to clipboardtransaction_created
status toCopy to clipboardFulfillment
Copy to clipboardshipped
Payload
shippo.transaction_created.return_label
Triggered when the
webhook receives a return label transactionCopy to clipboardtransaction_created
Payload
shippo.transaction_updated.payload
Triggered when the
webhook receives an updated transactionCopy to clipboardtransaction_updated
Payload
shippo.track_updated.payload
Triggered when the
webhook receives an updated trackCopy to clipboardtrack_updated
Payload
Shippo Node Client
This plugin is using a forked version of the official shippo-node-client.
The fork adds support for the following endpoints:
- live-rates
- service-groups
- user-parcel-templates
- orders/:id/packingslip
- ...
- Doc is WIP
The client is exposed on the
property ofCopy to clipboarduseClient
Copy to clipboardshippoClientService
See Shippo API Reference for methods
Release Policy
Versioning
Follows Semantic versioning (semver) principles.
Breaking Changes
Breaking change refers to a backwards incompatible change to the public interface or core feature.
The public interface and core features are declared and defined in this document. Breaking changes will be announced in advance, and once released the major version number is incremented.
Undocumented API and internal data structures are considered implementation details and are subject to change without notice. In other words, you are on your own when relying on undocumented usage.
Limitations
No support for customs declarations. Planned for future release.
Resources
Medusa Docs\
https://docs.medusajs.com/
Medusa Shipping Architecture:\
https://docs.medusajs.com/advanced/backend/shipping/overview

Build your own plugins
Develop your own plugins with our API to speed up your processes.
Make your plugin available via npm for it to be shared in our Plugin Library with the broader Medusa community.
.png)