SHshipengine
rates

Get Shipping Rates

Changed on

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/v1/rates

Request

  • Base URL
    https://api.shipengine.com
  • URL
    https://api.shipengine.com/v1/rates
  • Auth
    API key in header API-Key

Request body

Example request

{
  "rate_options": {
    "carrier_ids": [
      "se-28529731"
    ]
  }
}

Response

The request was a success.

shipment_idstring required

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

carrier_idstring

A string that uniquely identifies a ShipEngine 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.

shipping_rule_idstring

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

external_order_idstring nullable

ID that the Order Source assigned

external_shipment_idstring nullable

A unique user-defined key to identify a shipment. This can be used to retrieve the shipment.

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

shipment_numberstring nullable

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 ShipEngine.

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 ShipEngine resource, such as a carrier, label, shipment, etc.

is_returnboolean nullable

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

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

The possible delivery confirmation values

insurance_provider'none' | 'shipsurance' | '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 ShipEngine

comparison_rate_typestring nullable

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

zoneinteger nullable

Certain carriers base their rates off of custom zones that vary depending upon the ship_to and ship_from location

Example response

{
  "shipment_id": "se-28529731",
  "carrier_id": "se-28529731",
  "service_code": "usps_first_class_mail",
  "shipping_rule_id": "se-28529731",
  "items": [
    {
      "asin": "B00005N5PF"
    }
  ],
  "ship_date": "2018-09-23T00:00:00.000Z",
  "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",
    "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"
  },
  "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"
  },
  "customs": {
    "importer_of_record": {
      "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"
    },
    "customs_items": [
      {
        "customs_item_id": "se-28529731",
        "country_of_origin": "CA"
      }
    ]
  },
  "advanced_options": {
    "bill_to_country_code": "CA",
    "invoice_number": "IOC56888"
  },
  "tags": [
    {
      "tag_id": 8712,
      "name": "Fragile",
      "color": "#FF0000"
    }
  ],
  "packages": [
    {
      "shipment_package_id": "se-28529731",
      "package_id": "se-28529731",
      "package_code": "small_flat_rate_box",
      "tracking_number": "1Z932R800392060079",
      "content_description": "Hand knitted wool socks",
      "products": [
        {
          "country_of_origin": "CA",
          "vat_rate": 0.2
        }
      ]
    }
  ],
  "comparison_rate_type": "retail",
  "zone": 6,
  "rate_response": {
    "rates": [
      {
        "rate_id": "se-28529731",
        "carrier_id": "se-28529731",
        "zone": 6,
        "package_type": "package",
        "delivery_days": 5,
        "estimated_delivery_date": "2018-09-23T00:00:00.000Z"
      }
    ],
    "invalid_rates": [
      {
        "rate_id": "se-28529731",
        "carrier_id": "se-28529731",
        "zone": 6,
        "package_type": "package",
        "delivery_days": 5,
        "estimated_delivery_date": "2018-09-23T00:00:00.000Z"
      }
    ],
    "rate_request_id": "se-28529731",
    "shipment_id": "se-28529731",
    "created_at": "se-28529731",
    "errors": [
      {
        "message": "Body of request cannot be null.",
        "carrier_id": "se-28529731",
        "carrier_code": "dhl_express",
        "field_name": "shipment.ship_to.phone_number"
      }
    ]
  }
}

Changes

  • 6af91511d87eRevision changes
    • breaking

      the response property ////// became nullable for the status

    • breaking

      the response property ////// became nullable for the status

    • breaking

      the response property ////// became nullable for the status

    • breaking

      the response property ////// became nullable for the status

  • b81c65818a89Revision changes
    • info

      added the new optional request property //////

    • info

      added the optional property /// to the response with the status