feat: [MM2-160] easypost integration

[jakub-borek]

Easypost integration plugin.

Each shipping option is different carrier. Then each carrier can have multiple options of delivery - this will be available when calculating price for delivery, since we don't know them beforehand and easypost simply calculates all possible options for a given from/to delivery. Due to that, some changes on frontend are required.

Unfortunately to fetch available carriers a production api key is required. For local tests I recommend to use production key to set shipping options, then switch to test api key to test fulfillments, labels, tracking.

To do on frontend:

• On Vendor panel allow vendors to define shipping options with provider the same way that admin can. Currently not possible, though backend supports it
• When calculating price for easypost option, it will return different rates for carrier besides the lowest price. User should be able to see those options and select one. For example for USPS shipping options, rates could be: USPS Priority, USPS Express, USPS Ground. This is example returned body:

{
    "shipping_option": {
        "id": "so_01KERTN2Q3B04KFET9Y3HY8J7W",
        "name": "USPS",
        "price_type": "calculated",
        "service_zone_id": "serzo_01KERTK26291Q2BGCMMFW6RCKB",
        "shipping_profile_id": "sp_01KERTD2BY7MTQFBB4ANNX9B9N",
        "shipping_option_type_id": "sotype_01KERTD2E5FAGTMMVN7Z4FJX9T",
        "metadata": null,
        "calculated_price": {
            "calculated_amount": 45.98,
            "is_calculated_price_tax_inclusive": false,
            "shipment_id": "shp_f50a0d5f8f954bb0b1a9aa724799ec08",
            "rates": [
                {
                    "id": "rate_ad39458e41f449bfbb433e0b7aaf2db9",
                    "object": "Rate",
                    "created_at": "2026-01-12T10:40:59Z",
                    "updated_at": "2026-01-12T10:40:59Z",
                    "mode": "test",
                    "service": "Express",
                    "carrier": "USPS",
                    "rate": "189.35",
                    "currency": "USD",
                    "retail_rate": "212.65",
                    "retail_currency": "USD",
                    "list_rate": "189.35",
                    "list_currency": "USD",
                    "billing_type": "easypost",
                    "delivery_days": 2,
                    "delivery_date": null,
                    "delivery_date_guaranteed": false,
                    "est_delivery_days": 2,
                    "shipment_id": "shp_f50a0d5f8f954bb0b1a9aa724799ec08",
                    "carrier_account_id": "ca_0572c078b7a84122b57507747cdd850c",
                    "_params": {
                        "shipment": {
                            "from_address": {
                                "name": "test",
                                "street1": "417 Montgomery St",
                                "city": "San Francisco",
                                "state": "CA",
                                "zip": "94104",
                                "country": "US"
                            },
                            "to_address": {
                                "name": "null null",
                                "street1": "164 Townsend St",
                                "city": "San Francisco",
                                "state": "CA",
                                "zip": "94104",
                                "country": "US"
                            },
                            "parcel": {
                                "weight": 1000
                            }
                        }
                    }
                },
                {
                    "id": "rate_4a36da21247a47e781e9bbd8540dcab2",
                    "object": "Rate",
                    "created_at": "2026-01-12T10:40:59Z",
                    "updated_at": "2026-01-12T10:40:59Z",
                    "mode": "test",
                    "service": "Priority",
                    "carrier": "USPS",
                    "rate": "52.71",
                    "currency": "USD",
                    "retail_rate": "63.15",
                    "retail_currency": "USD",
                    "list_rate": "52.71",
                    "list_currency": "USD",
                    "billing_type": "easypost",
                    "delivery_days": 2,
                    "delivery_date": null,
                    "delivery_date_guaranteed": false,
                    "est_delivery_days": 2,
                    "shipment_id": "shp_f50a0d5f8f954bb0b1a9aa724799ec08",
                    "carrier_account_id": "ca_0572c078b7a84122b57507747cdd850c",
                    "_params": {
                        "shipment": {
                            "from_address": {
                                "name": "test",
                                "street1": "417 Montgomery St",
                                "city": "San Francisco",
                                "state": "CA",
                                "zip": "94104",
                                "country": "US"
                            },
                            "to_address": {
                                "name": "null null",
                                "street1": "164 Townsend St",
                                "city": "San Francisco",
                                "state": "CA",
                                "zip": "94104",
                                "country": "US"
                            },
                            "parcel": {
                                "weight": 1000
                            }
                        }
                    }
                },
                {
                    "id": "rate_1debd93ec8484d45b83413732a7e29c1",
                    "object": "Rate",
                    "created_at": "2026-01-12T10:40:59Z",
                    "updated_at": "2026-01-12T10:40:59Z",
                    "mode": "test",
                    "service": "GroundAdvantage",
                    "carrier": "USPS",
                    "rate": "45.98",
                    "currency": "USD",
                    "retail_rate": "56.05",
                    "retail_currency": "USD",
                    "list_rate": "45.98",
                    "list_currency": "USD",
                    "billing_type": "easypost",
                    "delivery_days": 2,
                    "delivery_date": null,
                    "delivery_date_guaranteed": false,
                    "est_delivery_days": 2,
                    "shipment_id": "shp_f50a0d5f8f954bb0b1a9aa724799ec08",
                    "carrier_account_id": "ca_0572c078b7a84122b57507747cdd850c",
                    "_params": {
                        "shipment": {
                            "from_address": {
                                "name": "test",
                                "street1": "417 Montgomery St",
                                "city": "San Francisco",
                                "state": "CA",
                                "zip": "94104",
                                "country": "US"
                            },
                            "to_address": {
                                "name": "null null",
                                "street1": "164 Townsend St",
                                "city": "San Francisco",
                                "state": "CA",
                                "zip": "94104",
                                "country": "US"
                            },
                            "parcel": {
                                "weight": 1000
                            }
                        }
                    }
                }
            ]
        },
        "amount": 45.98,
        "is_tax_inclusive": false
    }
}

• After user selects shipping option make sure to pass shipment_id and rate_id in data field on POST /store/carts/:id/shipping-methods endpoint, example body:

{
    "option_id": "so_01KERTN2Q3B04KFET9Y3HY8J7W",
    "data": {
        "shipment_id": "shp_f50a0d5f8f954bb0b1a9aa724799ec08",
        "rate_id": "rate_ad39458e41f449bfbb433e0b7aaf2db9"
    }
}

Otherwise it will throw error.

[medusajs]

Name	Deployment Status	Preview Link	Timestamp
Api - mercur - sales sandbox	✅ Ready	Preview	Thu, 22 Jan 2026 09:04:43 GMT

[railway-app]

This PR was not deployed automatically as @jakub-borek does not have access to the Railway project.

In order to get automatic PR deploys, please add @jakub-borek to your workspace on Railway.