Sign in
latestOpenAPI 3.1.0MIT2026-08-221643491.4 MB

d3d8c21cd227

rates

Get shipping rates

<aside class="access" aria-label="Endpoint access"> <table class="access__table"> <thead> <tr> <th class="access__table-header">Products</th> <th class="access__table-header">Plans</th> </tr> </thead> <tbody> <tr> <td class="access__table-cell access__product"> <img class="access__logo" src="/static/logos/shipstation-api-logo.svg" alt="ShipStation API Logo" loading="lazy" decoding="async"/> <div class="access__sub">Formerly ShipEngine</div> </td> <td class="access__table-cell access__plans"> <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-api-free.md" class="access__plan">Free</a> <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-api-advanced-enterprise.md" class="access__plan">Advanced</a> <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-api-advanced-enterprise.md" class="access__plan">Enterprise</a> </td> </tr> <tr> <td class="access__table-cell"> <img class="access__logo" src="/static/logos/shipstation-logo.svg" alt="ShipStation Logo" loading="lazy" decoding="async"/> </td> <td class="access__table-cell access__plans"> <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-free-starter.md" class="access__plan access__plan--off">Free</a> <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-free-starter.md" class="access__plan access__plan--off">Starter</a> <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-standard-premium.md" class="access__plan">Standard</a> <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-standard-premium.md" class="access__plan">Premium</a> </td> </tr> </tbody> </table> <footer class="access__footer"> <a class="access__help" href="/apis/@shipstation-v2/docs/getting-started/products-and-plans.md"> Learn about products and plans <img src="/static/icons/external-link.svg" alt="External Link Icon" style="width: 16px;" loading="lazy" decoding="async"/> </a> </footer> </aside>

It's not uncommon that you want to give your customer the choice between whether they want to ship the fastest, cheapest, or the most trusted route. Most companies don't solely ship things using a single shipping option; so we provide functionality to show you all your options!

post/v2/rates

Request body

OR

Example request

{
  "shipment_id": "se-28529731",
  "rate_options": {
    "carrier_ids": [
      "se-28529731"
    ],
    "calculate_tax_amount": true,
    "is_return": true
  }
}

Response

The request was a success.

shipment_idstring required

A string that uniquely identifies a ShipStation resource, such as a carrier, label, shipment, etc.

carrier_idstring

A string that uniquely identifies a ShipStation resource, such as a carrier, label, shipment, etc.

service_codestring

A [carrier service], such as fedex_ground, usps_first_class_mail, flat_rate_envelope, etc.

requested_shipment_servicestring

The requested shipment service

external_order_idstring

ID that the Order Source assigned

hold_until_datestring date-time

Date to hold the shipment until

ship_by_datestring date-time

Date by which the shipment should be shipped

deliver_by_datestring date-time

Date by which the shipment should be delivered

store_idstring

A string that uniquely identifies a ShipStation resource, such as a carrier, label, shipment, etc.

notes_from_buyerstring

Notes from the buyer

notes_to_buyerstring

Notes to the buyer

notes_for_giftstring

Gift notes

internal_notesstring

Internal notes from the seller

is_giftboolean

Indicates if the shipment is a gift

assigned_userstring

User assigned to the shipment

zoneinteger

Shipping zone

display_schemestring

Display scheme for the shipment

external_shipment_idstring

A user-defined key that identifies the source order. Multiple shipments can share the same external_shipment_id (common in split-shipping scenarios where one order results in multiple shipments). Functionally identical to orderKey in V1 API.

Warning: The external_shipment_id is limited to 50 characters. Any additional characters will be truncated.

shipment_numberstring

A non-unique user-defined number used to identify a shipment. If undefined, this will match the external_shipment_id of the shipment.

Warning: The shipment_number is limited to 50 characters. Any additional characters will be truncated.

ship_datestring date-time required

An ISO 8601 string that represents a date, but not a specific time. The value may contain a time component, but it will be set to 00:00:00 UTC by ShipStation .

created_atstring date-time required

An ISO 8601 string that represents a date and time.

modified_atstring date-time required

An ISO 8601 string that represents a date and time.

shipment_status'pending' | 'processing' | 'label_purchased' | 'cancelled' required

The possible shipment status values

warehouse_idstring

A string that uniquely identifies a ShipStation resource, such as a carrier, label, shipment, etc.

is_returnboolean

An optional indicator if the shipment is intended to be a return. Defaults to false if not provided.

confirmation'none' | 'delivery' | 'signature' | 'adult_signature' | 'adult_signature_restricted_delivery' | 'direct_signature' | 'delivery_mailed' | 'verbal_confirmation' | 'delivery_code' | 'age_verification_16_plus'

The possible delivery confirmation values

insurance_provider'none' | 'shipsurance' | 'parcelguard' | 'xcover' | 'carrier' | 'third_party' required

The possible insurance provider values

order_source_code'amazon_ca' | 'amazon_us' | 'brightpearl' | 'channel_advisor' | 'cratejoy' | 'ebay' | 'etsy' | 'jane' | 'groupon_goods' | 'magento' | 'paypal' | 'seller_active' | 'shopify' | 'stitch_labs' | 'squarespace' | 'three_dcart' | 'tophatter' | 'walmart' | 'woo_commerce' | 'volusion'

The order sources that are supported by ShipStation

comparison_rate_typestring

Calculate a rate for this shipment with the requested carrier using a ratecard that differs from the default. Only supported for UPS and USPS.

Example response

{
  "shipment_id": "se-28529731",
  "carrier_id": "se-28529731",
  "service_code": "usps_first_class_mail",
  "requested_shipment_service": "usps_priority_mail",
  "external_order_id": "1232434",
  "hold_until_date": "2025-01-15T00:00:00.000Z",
  "ship_by_date": "2025-01-15T00:00:00.000Z",
  "deliver_by_date": "2025-01-20T00:00:00.000Z",
  "retail_rate": {
    "amount": 12
  },
  "store_id": "se-28529731",
  "items": [
    {
      "name": "box",
      "sales_order_id": "12345",
      "sales_order_item_id": "1234556",
      "quantity": 1,
      "sku": "sku-1234",
      "bundle_sku": "bundle-123",
      "external_order_id": "123445",
      "external_order_item_id": "12",
      "asin": "B00005N5PF",
      "item_id": "1402291169813",
      "allocation_status": "allocated",
      "image_url": "https://example.com/image.jpg",
      "weight": {
        "value": 23
      },
      "unit_price": 88,
      "tax_amount": 5.5,
      "shipping_amount": 10,
      "inventory_location": "warehouse-a",
      "options": [
        {
          "name": "Color",
          "value": "Red"
        }
      ],
      "product_id": "10408926",
      "fullfilment_sku": "fulfill-123",
      "upc": "123456789012"
    }
  ],
  "notes_from_buyer": "Please handle with care",
  "notes_to_buyer": "Thank you for your order!",
  "notes_for_gift": "Happy Birthday!",
  "internal_notes": "Check packaging before shipping",
  "is_gift": true,
  "assigned_user": "user@example.com",
  "amount_paid": {
    "amount": 12
  },
  "shipping_paid": {
    "amount": 12
  },
  "tax_paid": {
    "amount": 12
  },
  "zone": 1,
  "display_scheme": "label",
  "tax_identifiers": [
    {
      "issuing_authority": "US",
      "value": "value"
    }
  ],
  "external_shipment_id": "1234556",
  "shipment_number": "10001",
  "ship_date": "2018-09-23T00:00:00Z",
  "created_at": "2018-09-23T15:00:00.000Z",
  "modified_at": "2018-09-23T15:00:00.000Z",
  "ship_to": {
    "name": "John Doe",
    "phone": "+1 204-253-9411 ext. 123",
    "email": "example@example.com",
    "company_name": "The Home Depot",
    "address_line1": "1999 Bishop Grandin Blvd.",
    "address_line2": "Unit 408",
    "address_line3": "Building #7",
    "city_locality": "Winnipeg",
    "state_province": "Manitoba",
    "postal_code": "78756-3717",
    "country_code": "CA",
    "instructions": "any instruction",
    "geolocation": [
      {
        "type": "what3words",
        "value": "cats.with.thumbs"
      }
    ]
  },
  "ship_from": {
    "name": "John Doe",
    "phone": "+1 204-253-9411 ext. 123",
    "email": "example@example.com",
    "company_name": "The Home Depot",
    "address_line1": "1999 Bishop Grandin Blvd.",
    "address_line2": "Unit 408",
    "address_line3": "Building #7",
    "city_locality": "Winnipeg",
    "state_province": "Manitoba",
    "postal_code": "78756-3717",
    "country_code": "CA",
    "instructions": "any instructions",
    "geolocation": [
      {
        "type": "what3words",
        "value": "cats.with.thumbs"
      }
    ]
  },
  "warehouse_id": "se-28529731",
  "return_to": {
    "name": "John Doe",
    "phone": "+1 204-253-9411 ext. 123",
    "email": "example@example.com",
    "company_name": "The Home Depot",
    "address_line1": "1999 Bishop Grandin Blvd.",
    "address_line2": "Unit 408",
    "address_line3": "Building #7",
    "city_locality": "Winnipeg",
    "state_province": "Manitoba",
    "postal_code": "78756-3717",
    "country_code": "CA",
    "instructions": "any instructions",
    "geolocation": [
      {
        "type": "what3words",
        "value": "cats.with.thumbs"
      }
    ]
  },
  "is_return": true,
  "customs": {
    "terms_of_trade_code": "ddp",
    "contents": "gift",
    "non_delivery": "return_to_sender"
  },
  "advanced_options": {
    "bill_to_account": "123456789",
    "bill_to_country_code": "CA",
    "bill_to_postal_code": "28005",
    "contains_alcohol": true,
    "delivered_duty_paid": true,
    "dry_ice": true,
    "dry_ice_weight": {
      "value": 23
    },
    "non_machinable": true,
    "saturday_delivery": true,
    "fedex_freight": {
      "shipper_load_and_count": "shipper_load_and_count",
      "booking_confirmation": "today"
    },
    "use_ups_ground_freight_pricing": true,
    "freight_class": "77.5",
    "custom_field1": "custom field 1",
    "custom_field2": "custom field 2",
    "custom_field3": "custom field 3",
    "additional_handling": true,
    "shipper_release": true,
    "collect_on_delivery": {
      "payment_amount": {
        "amount": 12
      }
    },
    "third_party_consignee": true,
    "dangerous_goods": true,
    "dangerous_goods_contact": {
      "name": "Michael Robinson",
      "phone": "123456578789"
    },
    "movement_indicator": "b2b",
    "windsor_framework_details": {
      "movement_indicator": "b2b",
      "not_at_risk": true
    },
    "ancillary_endorsements_option": "forward",
    "return_pickup_attempts": 3,
    "netstamps_options": {
      "row": 1,
      "column": 1
    }
  },
  "tags": [
    {
      "name": "Fragile"
    }
  ],
  "packages": [
    {
      "shipment_package_id": "se-28529731",
      "package_id": "se-28529731",
      "package_code": "small_flat_rate_box",
      "package_name": "Flat Rate Envelope",
      "weight": {
        "value": 23
      },
      "dimensions": {
        "length": 2,
        "width": 2,
        "height": 1
      },
      "insured_value": {
        "amount": 12
      },
      "label_messages": {
        "reference1": "Reference",
        "reference2": "Reference 2",
        "reference3": "Reference 3"
      },
      "external_package_id": "se-1234545",
      "content_description": "Hand knitted wool socks",
      "products": [
        {
          "description": "a minimum description",
          "quantity": 1,
          "value": {
            "amount": 12
          },
          "weight": {
            "value": 23
          },
          "harmonized_tariff_code": "3926.10",
          "country_of_origin": "CA",
          "unit_of_measure": "pound",
          "sku": "sku-1223344",
          "sku_description": "this is a description",
          "mid_code": "GBCOM15BRI",
          "product_url": "https://myproduct.com",
          "vat_rate": 0.2,
          "dangerous_goods": [
            {
              "id_number": "1234r1",
              "shipping_name": "things with dangerous goods",
              "technical_name": "chloric acid",
              "product_class": "1987",
              "product_class_subsidiary": "1987",
              "packaging_group": "ii",
              "dangerous_amount": {
                "amount": 12,
                "unit": "GBP"
              },
              "quantity": 1,
              "packaging_instruction": "Packaging materials and containers that are in contact with food products must comply with the provisions established by Regulation ",
              "packaging_instruction_section": "section_1",
              "packaging_type": "X",
              "transport_mean": "ground",
              "transport_category": "6.1",
              "regulation_authority": "AEAT",
              "regulation_level": "excepted_quantity",
              "tunnel_code": "all",
              "additional_description": "any description"
            }
          ],
          "manufacturer_product_id": "012345678905",
          "manufacturer_ns_product_id": "MY-SKU-12345",
          "cpsc_certificates": [
            {
              "certifier_id": "CERT-12345",
              "certificate_version_id": "v1.0"
            }
          ]
        }
      ]
    }
  ],
  "total_weight": {
    "value": 3
  },
  "comparison_rate_type": "retail",
  "rate_response": {
    "rates": [
      {
        "rate_id": "se-28529731",
        "carrier_id": "se-28529731",
        "shipping_amount": {
          "amount": 12
        },
        "insurance_amount": {
          "amount": 12
        },
        "confirmation_amount": {
          "amount": 12
        },
        "other_amount": {
          "amount": 12
        },
        "requested_comparison_amount": {
          "amount": 12
        },
        "tax_amount": {
          "amount": 12
        },
        "zone": 6,
        "package_type": "package",
        "delivery_days": 5,
        "guaranteed_service": true,
        "estimated_delivery_date": "2018-09-23T00:00:00Z",
        "carrier_delivery_days": "22",
        "ship_date": "2024-10-22T00:00:00Z",
        "negotiated_rate": true,
        "service_type": "next_day",
        "service_code": "usps_priority_mail_express",
        "trackable": true,
        "carrier_code": "stamps_com",
        "carrier_nickname": "Free",
        "carrier_friendly_name": "free",
        "rate_details": [
          {
            "rate_detail_type": "shipping",
            "carrier_description": "Shipping",
            "carrier_billing_code": "BaseServiceCharge",
            "amount": {
              "amount": 12
            },
            "billing_source": "carrier"
          }
        ]
      }
    ],
    "invalid_rates": [
      {
        "rate_id": "se-28529731",
        "carrier_id": "se-28529731",
        "shipping_amount": {
          "amount": 12
        },
        "insurance_amount": {
          "amount": 12
        },
        "confirmation_amount": {
          "amount": 12
        },
        "other_amount": {
          "amount": 12
        },
        "requested_comparison_amount": {
          "amount": 12
        },
        "tax_amount": {
          "amount": 12
        },
        "zone": 6,
        "package_type": "package",
        "delivery_days": 5,
        "guaranteed_service": true,
        "estimated_delivery_date": "2018-09-23T00:00:00Z",
        "carrier_delivery_days": "22",
        "ship_date": "2024-10-22T00:00:00Z",
        "negotiated_rate": true,
        "service_type": "next_day",
        "service_code": "usps_priority_mail_express",
        "trackable": true,
        "carrier_code": "stamps_com",
        "carrier_nickname": "Free",
        "carrier_friendly_name": "free",
        "rate_details": [
          {
            "rate_detail_type": "shipping",
            "carrier_description": "Shipping",
            "carrier_billing_code": "BaseServiceCharge",
            "amount": {
              "amount": 12
            },
            "billing_source": "carrier"
          }
        ]
      }
    ],
    "rate_request_id": "se-28529731",
    "shipment_id": "se-28529731",
    "created_at": "se-28529731",
    "errors": [
      {
        "message": "Body of request cannot be null.",
        "field_name": "inventory_warehouse_id",
        "field_value": "invalid-id"
      }
    ]
  }
}