> ## Documentation Index > Fetch the complete documentation index at: https://docs.smartsend.io/llms.txt > Use this file to discover all available pages before exploring further. # Get shipping rates > Returns available shipping rates for a specific shipment, including estimated delivery windows and cost prices. Only shows rates available for the authenticated team based on their carrier accounts. Cost prices may be null when unknown. Sender address is automatically taken from the authenticated team's settings. ## OpenAPI ````yaml /openapi-v2beta.json post /team/{team}/rates openapi: 3.1.0 info: title: Smart Send API description: >- Unified API for shipping operations including service points, routing, and rates. ## Localization The API performs language negotiation to determine the most suitable language for translatable content (such as service names, tracking descriptions, and error messages). The negotiation considers: 1. The `Accept-Language` request header (if provided) 2. The team's configured default language 3. English as the ultimate fallback The resolved language is used for all translatable strings in the response. ## Idempotency Write operations support **idempotency keys** so you can safely retry a request after a network error, timeout, or uncertain outcome without risking a duplicate side effect such as booking the same shipment twice. Idempotency is opt-in: include an `Idempotency-Key` header on a write request (`POST` or `DELETE`) to enable it. Requests sent without the header are not deduplicated. The key is a client-generated string of 16–128 characters (letters, digits, `.`, `_`, `-`) and is compared as-is, so it is case-sensitive. When a key is reused with an identical payload within 24 hours, the API returns the original response (status code and body) without re-executing the operation and sets the `Idempotency-Replayed: true` response header. Reusing a key with a different payload returns `422 Unprocessable Entity`. If the original request is still being processed, the retry returns `409 Conflict` with a `Retry-After` header indicating when to try again. Keys are scoped per client and expire automatically after the 24-hour window. See the [idempotency guide](https://docs.smartsend.io/api-reference/idempotency) for requirements and examples. ## User-Agent We recommend including a descriptive `User-Agent` header with every request, following the `Product/Version (Comments)` pattern from [RFC 7231](https://datatracker.ietf.org/doc/html/rfc7231#section-5.5.3). A good User-Agent helps us identify your integration and speeds up debugging when you contact support. Example: `smart-send-logistics/8.1.0 (WooCommerce/8.5.0; WordPress/6.4.2; PHP/8.1)` ## Request-ID We recommend including a unique `Request-ID` header with every request. The value is echoed back in the response and included in internal logs, making it possible to correlate logs from your implementation with logs in Smart Send. This is especially useful when contacting support about a specific request. version: 2.0.0-beta contact: name: Smart Send url: https://www.smartsend.io servers: - url: https://app.smartsend.io/api/v2 description: Production security: - bearerAuth: [] - oauth2: [] tags: - name: Teams description: Teams available to the authenticated user - name: Service Points description: Pickup points and delivery locations - name: Routing description: Reference data (carriers, services, addons) and route availability - name: Rates description: Shipping rates and pricing for specific shipments - name: Tracking description: Shipment tracking information and event history - name: Shipments description: Create and manage shipments - name: Booking description: Booking of shipments externalDocs: description: Booking documentation url: https://docs.smartsend.io/features/booking - name: Booking batches description: |- Batch operations for booking multiple shipments asynchronously. Processing operates after the _first-in-first-out_ principle. externalDocs: description: Batch booking documentation url: https://docs.smartsend.io/features/booking#batch-booking paths: /team/{team}/rates: post: tags: - Rates summary: Get shipping rates description: >- Returns available shipping rates for a specific shipment, including estimated delivery windows and cost prices. Only shows rates available for the authenticated team based on their carrier accounts. Cost prices may be null when unknown. Sender address is automatically taken from the authenticated team's settings. operationId: listRates parameters: - $ref: '#/components/parameters/team' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/Request-ID' - $ref: '#/components/parameters/Idempotency-Key' - name: carriers in: query required: false schema: type: array items: type: string description: Only include rates from these carriers (e.g., postnord, gls) - name: is_return in: query required: false schema: type: boolean description: Filter by return services (true) or outbound services (false) requestBody: required: true content: application/json: schema: type: object required: - currency - parties - parcels properties: currency: type: string description: ISO 4217 currency code for all monetary values examples: - EUR parties: type: object required: - receiver properties: receiver: type: object required: - address properties: address: $ref: '#/components/schemas/Address' description: Receiver address for rate calculation description: Parties involved in the shipment parcels: type: array items: $ref: '#/components/schemas/Parcel' minItems: 1 description: List of parcels to be shipped responses: '200': description: Rates retrieved successfully headers: Correlation-ID: $ref: '#/components/headers/Correlation-ID' Request-ID: $ref: '#/components/headers/Request-ID' Idempotency-Replayed: $ref: '#/components/headers/Idempotency-Replayed' content: application/json: schema: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/Rate' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/ValidationError' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' security: - bearerAuth: [] - oauth2: - rates:read components: parameters: team: name: team in: path required: true schema: type: string minLength: 1 examples: - ad9546c1-393e-49a5-9a72-5cc146c9bec5 description: Team identifier. All resources are scoped to this team. Accept-Language: name: Accept-Language in: header required: false schema: type: string default: en examples: - da-DK, da;q=0.9, en;q=0.8 description: >- Preferred language(s) for translatable content using BCP 47 language tags. Supports quality values (q-factors) for priority ordering. The API negotiates the best available language based on this header, the team's configured language, and available translations. If omitted, the team's default language is used. Request-ID: name: Request-ID in: header required: false schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._-]{1,128}$ description: >- Any value passed in this request will be returned in the same header. This can be used to correlate requests between client and server. examples: uuid: summary: UUID v4 value: 3f5d9a8e-8e6f-4d9b-9d9c-9c6b3db2d1a0 opaque: summary: Opaque client-generated key value: booking-12345-at-1768609378 Idempotency-Key: name: Idempotency-Key in: header required: false description: >- Optional key that makes a write request idempotent so it can be safely retried. Reusing the key with an identical payload within 24 hours returns the original response without re-executing the operation (with an `Idempotency-Replayed: true` response header); reusing it with a different payload returns 422, and retrying while the original is still processing returns 409 with a `Retry-After` header. Use a client-generated, case-sensitive string of 16–128 characters (letters, digits, `.`, `_`, `-`). Deriving it deterministically from the request — for example the order ID combined with a hash of the payload — lets retries reuse the same key without storing it. See https://docs.smartsend.io/api-reference/idempotency. schema: type: string minLength: 16 maxLength: 128 pattern: ^[A-Za-z0-9._-]{16,128}$ examples: uuid: summary: UUID v4 value: 3f5d9a8e-8e6f-4d9b-9d9c-9c6b3db2d1a0 derived: summary: Deterministic key derived from the request value: >- order-4521_9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08 schemas: Address: type: object required: - address_lines - postal_code - city - country - administrative_area properties: address_lines: type: - 'null' - array items: type: string maxItems: 3 description: Street address lines (e.g., street name, building, floor) examples: - - 3200 Whitehaven St. NW - Building A, Floor 2 postal_code: type: - 'null' - string description: Postal/ZIP code examples: - '20008' city: type: string description: City examples: - Washington country: type: string minLength: 2 maxLength: 2 description: ISO 3166-1 alpha-2 country code examples: - US administrative_area: type: - 'null' - string minLength: 2 maxLength: 3 description: >- The sub-national subdivision code (e.g., state, province, or department) representing the suffix part of the ISO 3166-2 standard. This field should contain only the characters following the hyphen. For example, for 'US-NY', provide 'NY'; for 'JP-13', provide '13' examples: - DC Parcel: type: object properties: gross_weight: type: - 'null' - number minimum: 0 description: >- Weight of the parcel including both packaging and content (in the shipment's weight_unit) length: type: - 'null' - number minimum: 0 description: Length in millimeters width: type: - 'null' - number minimum: 0 description: Width in millimeters height: type: - 'null' - number minimum: 0 description: Height in millimeters items: type: - 'null' - array items: $ref: '#/components/schemas/ParcelItem' description: Items contained in this parcel required: - gross_weight - length - width - height - items Rate: type: object required: - available - delivery - cost_price - delivery_window - cutoff - addons properties: available: type: boolean description: >- Whether this service is available for the team (based on carrier account) delivery: $ref: '#/components/schemas/DeliveryInfoBase' description: Shipping service information for this rate. cost_price: description: Cost price for this service. Null when price is unknown. anyOf: - type: 'null' - $ref: '#/components/schemas/CostPrice' delivery_window: description: Estimated delivery window based on cutoff times and current time anyOf: - type: 'null' - $ref: '#/components/schemas/DateTimeWindow' cutoff: type: - 'null' - string format: date-time description: Cutoff time for same-day handling addons: type: - 'null' - array items: $ref: '#/components/schemas/RateAddon' description: Available addons for this service ParcelItem: type: object properties: quantity: type: - 'null' - number minimum: 0 description: Quantity of this item net_weight: type: - 'null' - number minimum: 0 description: >- Weight of all items excluding any packaging (in the shipment's weight_unit) tariff_code: type: - 'null' - string description: HS tariff code for customs country_of_origin: type: - 'null' - string minLength: 2 maxLength: 2 description: ISO 3166-1 alpha-2 country code of origin examples: - CN dangerous_goods: type: - 'null' - array items: $ref: '#/components/schemas/DangerousGood' description: Dangerous goods contained in this item required: - quantity - net_weight - tariff_code - country_of_origin - dangerous_goods DeliveryInfoBase: type: object description: Base shipping service information with carrier details and addons. properties: carrier_code: type: - 'null' - string description: Carrier code readOnly: true examples: - postnord carrier_name: type: - 'null' - string description: Human-readable carrier name readOnly: true examples: - PostNord carrier_logo_url: type: - 'null' - string format: uri description: URL to the carrier's logo image readOnly: true carrier_icon_url: type: - 'null' - string format: uri description: URL to the carrier's icon image readOnly: true service_code: type: - 'null' - string description: Full service code (carrier_code + '_' + service suffix) readOnly: true examples: - postnord_agent service_name: type: - 'null' - string description: Localized human-readable service name readOnly: true examples: - Pickup Point is_pickup: type: - 'null' - boolean description: Whether this service delivers to pickup points readOnly: true is_return: type: - 'null' - boolean description: Whether this is a return service readOnly: true addons: type: - 'null' - array items: $ref: '#/components/schemas/Addon' description: Available or selected addons required: - carrier_code - carrier_name - carrier_logo_url - carrier_icon_url - service_code - service_name - is_pickup - is_return - addons CostPrice: type: object required: - amount properties: amount: type: integer description: Price amount in minor units (cents) excluding VAT DateTimeWindow: type: object required: - earliest - latest properties: earliest: type: string format: date-time description: Earliest estimated delivery (ISO 8601 datetime) examples: - '2025-01-02T00:00:00Z' latest: type: string format: date-time description: Latest estimated delivery (ISO 8601 datetime) examples: - '2025-01-04T23:59:59Z' RateAddon: type: object required: - code - name - cost_price properties: code: type: string description: Addon code examples: - SIGNATURE name: type: string description: Localized addon name examples: - Signature cost_price: description: Additional cost price for this addon anyOf: - type: 'null' - $ref: '#/components/schemas/CostPrice' ErrorResponse: type: object required: - message properties: message: type: string description: Human-readable error message examples: - Something unexpected happened. ValidationErrorResponse: type: object required: - message - errors properties: message: type: string description: Human-readable error message summarizing the validation failure errors: type: object additionalProperties: type: array items: type: string description: >- Object containing field names as keys and arrays of error messages as values examples: - message: The given data was invalid. errors: field_name: - The field name is required. RateLimitErrorResponse: type: object required: - message properties: message: type: string description: Human-readable error message indicating rate limit exceeded DangerousGood: type: object required: - un_number - class - un_packing_group - tunnel_restriction_code - net_weight - quantity - environmentally_hazardous properties: un_number: type: string description: UN number (e.g., '1202', '1950') class: type: string description: Dangerous goods class (e.g., '1', '2.1', '3', '8') un_packing_group: type: - 'null' - string description: UN packing group (e.g., 'I', 'II', 'III') tunnel_restriction_code: type: - 'null' - string enum: - A - B - C - D - E description: ADR tunnel restriction code. A=no restrictions, E=most restrictive net_weight: type: - 'null' - number minimum: 0 description: Net weight of this dangerous good (in the shipment's weight_unit) quantity: type: - 'null' - number minimum: 0 description: Quantity of this dangerous good environmentally_hazardous: type: - 'null' - boolean description: Whether this is environmentally hazardous Addon: type: object required: - code - name properties: code: type: string description: Addon code (SCREAMING_SNAKE_CASE) examples: - SIGNATURE name: type: string description: Localized human-readable addon name readOnly: true examples: - Signature headers: Correlation-ID: description: >- Unique identifier for the request, useful for debugging and support. The id is automatically assigned to each request and can helps trace the request in system logs. Provide this value in case of any errors helps debugging. schema: type: string format: uuid examples: - 550e8400-e29b-41d4-a716-446655440000 Request-ID: description: >- If the request contained a `Request-ID` then the same value is returned as the `Request-ID`. This can be used to correlate requests between client and server. schema: type: string Idempotency-Replayed: description: >- Present and set to `true` when the response is a replay of an earlier request with the same `Idempotency-Key`, rather than a newly executed operation. schema: type: boolean examples: - true Retry-After: description: Number of seconds to wait before retrying the request. schema: type: integer examples: - 30 responses: Unauthorized: description: Authentication credentials were missing or invalid headers: Correlation-ID: $ref: '#/components/headers/Correlation-ID' Request-ID: $ref: '#/components/headers/Request-ID' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Forbidden: description: The authenticated user does not have permission to perform this action headers: Correlation-ID: $ref: '#/components/headers/Correlation-ID' Request-ID: $ref: '#/components/headers/Request-ID' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Conflict: description: >- A request with the same `Idempotency-Key` is still being processed. Wait for the duration in the `Retry-After` header, then retry. See https://docs.smartsend.io/api-reference/idempotency. headers: Correlation-ID: $ref: '#/components/headers/Correlation-ID' Request-ID: $ref: '#/components/headers/Request-ID' Retry-After: $ref: '#/components/headers/Retry-After' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' ValidationError: description: The request data failed validation headers: Correlation-ID: $ref: '#/components/headers/Correlation-ID' Request-ID: $ref: '#/components/headers/Request-ID' content: application/json: schema: $ref: '#/components/schemas/ValidationErrorResponse' TooManyRequests: description: Rate limit exceeded. Wait before retrying. headers: Correlation-ID: $ref: '#/components/headers/Correlation-ID' Request-ID: $ref: '#/components/headers/Request-ID' Retry-After: $ref: '#/components/headers/Retry-After' content: application/json: schema: $ref: '#/components/schemas/RateLimitErrorResponse' InternalServerError: description: An unexpected error occurred on the server headers: Correlation-ID: $ref: '#/components/headers/Correlation-ID' Request-ID: $ref: '#/components/headers/Request-ID' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' ServiceUnavailable: description: The service is temporarily unavailable. Please try again later. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: bearerAuth: type: http scheme: bearer oauth2: type: oauth2 description: OAuth 2.0 Authorization Code flow for API access flows: authorizationCode: authorizationUrl: https://app.smartsend.io/oauth/authorize tokenUrl: https://app.smartsend.io/oauth/token scopes: service_points: Access service points and pickup locations routing: Access routing information (carriers, services, addons, routes) tracking:read: Access shipment tracking information rates:read: Get shipping rates and pricing shipment:read: Read shipment information shipment:write: Create and manage shipments ````