# Get Shipping Rates > `POST /shipping-addresses/{shipping_address_id}/rate` Web page: https://reference.earthclassmail.com/v1/rest-api/spec/operations/getshippingrates/ URL: `POST https://api.earthclassmail.com/v1/shipping-addresses/{shipping_address_id}/rate` Retrieves available shipping rates for shipping the given pieces to a shipping address. Rates are fetched in real time from shipping providers. Pass the `id` of the chosen rate as `rate_id` to createShipment before the rate's `expired_at`. The pieces, insurance and customs details used for the shipment are taken from the rate request, so request the rate with the same options you want to ship with. International shipments need customs information: either `custom_items` (each with a description and declared value, plus an `hs_tariff_code` when the shipping address has `requires_hs_tariff_codes`), or a `customs_description` and `declared_value_in_cents`. ## Authorization Send your API key in the `x-api-key` header. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `shipping_address_id` | path | yes | string | | ## Request body Required. Content type: `application/json` Type: `GetShippingRateEstimateRequest` Example — Domestic: ```json { "items": [ { "piece_id": 1234000 }, { "piece_id": 1234001 } ] } ``` Example — Insured domestic: ```json { "items": [ { "piece_id": 123456789 } ], "is_insured": true, "declared_value_in_cents": 100000 } ``` Example — International: ```json { "items": [ { "piece_id": 120000 } ], "custom_items": [ { "description": "men's cotton trousers", "declared_value_in_cents": 20000, "hs_tariff_code": "620520" } ] } ``` ## Responses ### 200 Success Content type: `application/json` Type: `GetShippingRateEstimateResponse` Example: ```json { "rates": [ { "carrier_service": "Express", "carrier_type": "USPS - Express", "created_at": "2020-05-10T10:00:00Z", "expired_at": "2020-05-13T10:00:00Z", "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "price_in_cents": 5335, "tracking_available": true }, { "carrier_service": "Priority", "carrier_type": "USPS - Priority", "created_at": "2020-05-10T10:00:00Z", "expired_at": "2020-05-13T10:00:00Z", "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "price_in_cents": 1695, "tracking_available": true }, { "carrier_service": "GroundAdvantage", "carrier_type": "USPS - Ground Advantage", "created_at": "2020-05-10T10:00:00Z", "expired_at": "2020-05-13T10:00:00Z", "id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "price_in_cents": 945, "tracking_available": true } ] } ``` ### 401 The `x-api-key` header is missing or the key is not valid, or the caller can't access an ID in the request. IDs that don't exist return the same response as IDs the caller can't access. Content type: `application/json` Type: `Error` Example — Missing API key: ```json { "error": { "code": 401, "message": "The request does not include a valid access token. Please provide a valid access token.", "type": "Authorization" } } ``` Example — Invalid API key: ```json { "error": { "code": 401, "message": "x-api-key: x-api-key is invalid", "type": "REST" } } ``` Example — No access to resource: ```json { "error": { "code": 401, "message": "User does not have access to requested resource.", "type": "Authorization" } } ``` ### 404 The referenced resource is accessible, but the requested item does not exist, for example a pending operation. IDs the caller can't access, or that don't exist at all, return `401` instead. Content type: `application/json` Type: `Error` Example: ```json { "error": { "code": 404, "message": "piece_id: Piece with ID 14460059 does not have outstanding Operation of type Recycle.", "type": "REST" } } ``` ### 422 The request body failed validation. The message names the invalid field. Content type: `application/json` Type: `Error` Example: ```json { "error": { "code": 422, "message": "label: must have a value", "type": "REST", "fields": {} } } ``` ## Schemas ### Error Error envelope returned with 4xx and 5xx responses. - `error` (object) - `code` (integer): Usually the HTTP status code. It can differ; a request to an unknown path returns HTTP 400 with code 500. - `message` (string): Human-readable description of the error. - `type` (string): The kind of error, for example `Authorization` or `REST`. - `fields` (object): Returned only with `422` responses. It may give more details about what failed validation, as lists of messages keyed by the name of the input. ### GetShippingRateEstimateRequest - `items` (array of `GetShippingRateEstimateRequestItem`, required): The pieces to ship. Required, at least one. - `custom_items` (array of `GetShippingRateEstimateRequestCustomItem`): Customs line items describing the contents, for international shipments. - `signature_on_delivery` (boolean): Require a signature on delivery. Default: `false`. - `is_insured` (boolean): Insure the shipment. Set `declared_value_in_cents` to the insured value. Default: `false`. - `declared_value_in_cents` (number or null): Total declared value of the shipment, in cents. Used for insurance, and for customs when `custom_items` is not given. Rounded to whole cents. - `customs_description` (string): Description of the contents for customs, for international shipments without `custom_items`. ### GetShippingRateEstimateResponse - `rates` (array of `ShippingRate`) - `insurance` (`GetShippingRateEstimateInsurance`) - `error` (string) ### GetShippingRateEstimateInsurance - `total_insured_value_in_cents` (integer) - `price_in_cents` (integer) ### GetShippingRateEstimateRequestCustomItem - `declared_value_in_cents` (number, required): Declared value of the item, in cents. Rounded to whole cents. - `description` (string, required): Description of the item for customs. - `hs_tariff_code` (string): Harmonized System tariff code. Required when the shipping address has `requires_hs_tariff_codes`, unless `contents_type` is `Documents`. ### GetShippingRateEstimateRequestItem - `piece_id` (integer, required): ID of the piece to ship. - `declared_value_in_cents` (number or null): Declared value of this piece, in cents. Rounded to whole cents. - `customs_description` (string): Description of this piece for customs. - `has_complete_scan` (boolean) ### ShippingRate - `id` (string or null) - `carrier_type` (string) - `carrier_service` (string) - `price_in_cents` (integer) - `created_at` (string) - `expired_at` (string) - `tracking_available` (boolean)