EasyPost

The EasyPost app shows your customers live EasyPost carrier rates at checkout, and buys shipping labels from your EasyPost account, when you choose Buy EasyPost label on an order or automatically when an order is paid or submitted. After a label is bought, the app fulfills the order in Swell with the carrier and tracking number, and keeps the tracking status on the order until the parcel is delivered.

Rates and labels come from the carrier accounts in your EasyPost account, your own or the ones EasyPost provides, and labels are charged to your EasyPost account.

Install EasyPost from the Swell App Store, and set it up in your test environment before the live one.

When a cart's shipping address or items change, the app asks EasyPost for rates from your ship-from address to the customer's, for one parcel with the default dimensions. The weight is the sum of the items' shipping weights, or the default weight when no item has one. Each carrier service becomes a shipping option, named like USPS Priority or UPS Ground, with the estimated delivery days. The cheapest option is listed first.

By default, a label is bought only when you open an order and choose Actions > Buy EasyPost label. To buy labels automatically, set Buy labels to Automatically when an order is paid or Automatically when an order is submitted. Automatic labels are charged to your EasyPost account as soon as the order is paid or submitted.

To buy a label, the app creates an EasyPost shipment with the shipping and ship-from addresses, one parcel with the default dimensions, and the order number as the reference. Label service decides which rate it buys:

The cheapest rate is chosen among the services allowed by Services. The label costs EasyPost's price at the time it's bought, without your markup or handling fee, and the order's EasyPost tab shows it as Postage.

After buying, the app creates a Swell shipment for everything still to ship, with the carrier, service and tracking number, and saves the label link and tracking number on the order's EasyPost tab. With Create Swell shipment when a label is bought off, the label and tracking are saved on the tab but the order isn't fulfilled.

Canceled orders, orders with nothing to ship and orders that already have a label are skipped. If a purchase is interrupted after EasyPost bought the label, the next try uses that label instead of buying another.

If buying fails, the order's EasyPost tab shows Error with the reason. When EasyPost has a server error or doesn't answer in time, Swell tries an automatic purchase again. Other errors, such as an invalid address or no rates, aren't retried. To try again, choose Actions > Buy EasyPost label.

When an order ships to another country than your ship-from address, its label includes a customs declaration with one line for each item: the product name, quantity, line total in the order's currency, weight and SKU. The contents type is merchandise, and an undeliverable parcel is returned. The declaration is signed with the Customs signer, or the ship-from name when it's empty.

To declare a product's HS code and Country of origin, enter them on the product's EasyPost tab. The country of origin is a 2-letter country code, such as PT. Without an HS code, none is declared, and without a country of origin, your ship-from country is used.

To void a label, open the order and choose Actions > Void EasyPost label. The app asks EasyPost to refund the label. Unless the carrier rejects the refund, the app cancels the Swell shipment it created for the label, if any, and clears the tracking, and the order shows Label voided with the Refund status, Submitted or Refunded. You can then buy a new label. When the carrier rejects the refund, the label and its Swell shipment stay, and Refund shows Rejected.

Every hour, the app refreshes up to 20 labels that haven't been delivered, those checked longest ago first. For each, it saves the tracking status, the latest scan with its location, the estimated delivery and the tracking page on the order's EasyPost tab. To refresh right away, choose Actions > Refresh tracking now in the app settings.

A label is no longer refreshed once its tracking status is Delivered, Returned to sender, Failure, Cancelled or Error, or 60 days after it was bought.

The webhook is optional. With it, EasyPost sends tracking updates as carriers scan the parcel, and the app saves them on the order right away. Without it, tracking is refreshed every hour.

https://{store-id}:{public-key}@{store-id}.swell.store/functions/easypost/easypost-webhook

With a secret, the app rejects events that aren't signed with it. Without one, it accepts unsigned events. Either way, it loads the tracker from EasyPost with your API key before saving anything, so an event's content is never used as is.

Settings are in Apps > EasyPost > Settings and are saved separately for each environment.

Errors from buying a label are shown in Error on the order's EasyPost tab, and actions show their result in a message. The app also logs its errors. In the Swell dashboard, the logs are under Developer > Console > Logs.

Check that EasyPost is turned on in Settings > Shipping and saved, that Show EasyPost rates at checkout and Enabled are on, and that the ship-from address has a street, city, postal code and country code. Rates in another currency than the cart's, and services not listed in Services, aren't shown. Run Test connection to check the key. With a production key, it also lists your carrier accounts.

Check that Buy labels is set to buy automatically when the order is paid, or submitted, and that Enabled is on. Canceled orders and orders with nothing to ship are skipped. If buying failed, the reason is in Error on the order's EasyPost tab. To try again, choose Actions > Buy EasyPost label.

Enter the street, city, postal code and country code on the Ship-from address tab of the app settings, click Save settings, and buy the label again.

The order has no shipping country. Add the shipping address to the order, then choose Actions > Buy EasyPost label.

Label service is set to Only the service the customer chose, and the customer chose another shipping service. To buy the cheapest EasyPost rate for these orders, set Label service to Service the customer chose, else the cheapest.

EasyPost didn't quote the customer's service when the label was bought, for example after your carrier accounts changed. To buy the cheapest rate instead, set Label service to Service the customer chose, else the cheapest, then choose Actions > Buy EasyPost label.

No carrier quoted the parcel, or no rate matches Services. The message also lists up to 5 carrier messages from EasyPost. Check the addresses, the default parcel, the items' weights and your carrier accounts.

EasyPost took too long. Swell tries automatic purchases again, and if EasyPost bought the label before the time ran out, the next try uses it instead of buying another. To try again yourself, choose Actions > Buy EasyPost label.

Test connection shows this when EasyPost doesn't accept the API key. Check that you copied the whole key, and that it's the test key in the test environment and the production key in live.

Carriers refund only unused labels, within their own time limits. The label and its Swell shipment stay as they are.

Wait for the next hourly refresh, or choose Actions > Refresh tracking now in the app settings. When more than 20 labels are waiting, the message says so, and you can run it again. Labels bought more than 60 days ago aren't refreshed. If you use the webhook, check that it's in the same mode, test or production, as your API key.

EasyPost's webhook gets a 401 response with this message when Webhook secret is set in Swell but the event wasn't signed with the same secret. Enter the same secret in the app settings and in the EasyPost webhook. Tracking keeps refreshing every hour in the meantime.

EasyPost's webhook gets a 404 response with this message when the URL has no public key, a key from another store, or a key for an environment where the app isn't installed. Check the {public-key} part of the URL.

Uninstalling the app removes EasyPost rates from checkout and from Settings > Shipping, stops buying labels and refreshing tracking, and removes the app's settings page, the EasyPost tab, column and order actions, and the EasyPost tab on products. The webhook stops working, so EasyPost's deliveries to it fail. Uninstalling applies to the environment you are in, so remove the app from the test and live environments separately.

The EasyPost values saved on your orders and products are kept, and come back if you reinstall the app. Labels, shipments and webhooks in your EasyPost account stay there, and Swell shipments the app created stay on your orders. If you added the webhook, delete it in EasyPost under Account Settings > Webhooks.

The app stores its fields on orders under $app.easypost: easypost_status, easypost_shipment_id, easypost_tracker_id, easypost_tracking_code, easypost_tracking_url, easypost_label_url, easypost_carrier, easypost_service, easypost_label_cost, easypost_label_currency, easypost_label_date, easypost_refund_status, easypost_swell_shipment_id, easypost_tracking_status, easypost_tracking_details, easypost_tracking_date, easypost_eta, easypost_checked_at and easypost_error. On products, it stores easypost_hs_code and easypost_origin_country under $app.easypost.

Rate IDs are easypost_ plus the EasyPost carrier and service in lowercase, such as easypost_usps_priority, and each option also carries easypost_carrier and easypost_service. The label step matches the order's shipping.service against these IDs and buys the cheapest of the matching rates.

Each rate request and each label creates an EasyPost shipment with POST /shipments. Labels are bought with POST /shipments/{id}/buy and voided with POST /shipments/{id}/refund, and tracking is read with GET /trackers/{id}. Weights are sent in ounces and dimensions in inches, with one decimal. Swell item weights are line totals in the store's weight unit.

A label purchase gets 5 seconds to create the shipment and 4 to buy it. The EasyPost shipment ID is saved on the order before buying, so a retry finds a label bought by an interrupted run. EasyPost server errors, timeouts and Swell errors are rethrown so the platform retries the model event. EasyPost 4xx errors are saved on the order and not retried.

Customs declarations use contents_type: merchandise, eel_pfc: NOEEI 30.37(a) and non_delivery_option: return. Each item's value is its line total with the order's currency, and hs_tariff_number and origin_country come from the product's easypost_hs_code and easypost_origin_country. Swell shipments get the EasyPost carrier in lowercase as carrier, the readable service name as service, and the EasyPost shipment ID and tracking page in notes.

Each tracking refresh reads up to 20 orders sorted by easypost_checked_at, whose easypost_label_date is in the last 60 days, or whose order date is for labels bought before that field existed, and stops starting new ones after about 6 seconds. Tracker updates older than easypost_tracking_date are skipped, and a tracker whose shipment isn't the order's label is ignored.

The webhook handles tracker.created and tracker.updated and acknowledges other events. With a secret, it checks X-Hmac-Signature, which is hmac-sha256-hex= plus the HMAC-SHA256 of the raw body, keyed with the secret normalized to NFKD. It answers right away, then loads the tracker with GET /trackers/{id} before saving it.

Swell builds and maintains the EasyPost app. For help with the app, email support@swell.is. For questions about your EasyPost account, carriers or labels, contact EasyPost.