openapi: 3.1.0
info:
  title: Shipping price
  version: 2.0.0
  description: The Shipping prices API allows you to retrieve rates for a specific shipping method based on the specified `shipping_method_id`.
  contact:
    name: Sendcloud API Support
    url: https://www.sendcloud.dev
    email: contact@sendcloud.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
  - url: https://panel.sendcloud.sc/api/v2
    description: Sendcloud Production
tags:
  - name: Shipping price
paths:
  /shipping-price:
    parameters: []
    get:
      summary: Retrieve a shipping price
      operationId: sc-public-v2-scp-get-shipping_price
      security:
        - HTTPBasicAuth: []
        - OAuth2ClientCreds:
            - read:shipping-method
      x-mint:
        href: /api/v2/shipping-prices/retrieve-a-shipping-price
        content: |-
          <Info>
            OAuth2 scopes required: `read:shipping-method`. See [Scopes for OAuth apps](/api/v3/scopes).
          </Info>

          <Warning>
            **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3).
          </Warning>

          For users that have uploaded their own prices, the response will show the prices that have been uploaded.

          The response is an array of prices for all available receiver countries. If the `to_country` query parameter is present, the array will only contain one item.

          Note that `price` and `currency` will be `null` when no pricing is available for a receiver country.

          <Warning>
            If you have more than one active contract for a specific carrier, you must fill the `contract` attribute with your desired contract ID in your request. You can get your contract ID from the [Retrieve a list of contracts](/api/v2/contracts/retrieve-a-list-of-contracts) endpoint.
          </Warning>

          <Info>
            In order to view **remote surcharges**, you are required to provide the `to_country` and `to_postal_code`. Similarly, to access **zonal prices**, you need to provide `to_country`, `from_postal_code` and `to_postal_code`. This information ensures accurate and customized pricing based on the specific location, enabling you to understand any additional charges associated with remote areas and access pricing based on their designated zones.
          </Info>
      description: Retrieve shipping rate information for a specific `shipping_method_id` and `from_country`.
      parameters:
        - $ref: '#/components/parameters/shipping_method_id'
        - $ref: '#/components/parameters/from_country'
        - $ref: '#/components/parameters/to_country'
        - $ref: '#/components/parameters/weight'
        - $ref: '#/components/parameters/weight_unit'
        - $ref: '#/components/parameters/contract'
        - $ref: '#/components/parameters/from_postal_code'
        - $ref: '#/components/parameters/to_postal_code'
      tags:
        - Shipping price
      responses:
        '200':
          $ref: '#/components/responses/200'
        '400':
          $ref: '#/components/responses/400'
components:
  securitySchemes:
    HTTPBasicAuth:
      type: http
      description: Basic Authentication using API key and secrets is currently the main authentication mechanism.
      scheme: basic
    OAuth2ClientCreds:
      type: oauth2
      description: OAuth2 is a standardized protocol for authorization that allows users to share their private resources stored on one site with another site without having to provide their credentials. OAuth2 Client Credentials Grant workflow. This workflow is typically used for server-to-server interactions that require authorization to access specific resources.
      flows:
        clientCredentials:
          tokenUrl: https://account.sendcloud.com/oauth2/token/
          scopes:
            read:analytics: View your shipping analytics
            read:audit-log: View your account's audit log
            read:brand: View your brands
            write:brand: Manage your brands
            write:carrier: Configure carriers and contracts
            read:checkout: View your dynamic checkout configurations and templates
            read:event-subscription: View your event subscriptions
            write:event-subscription: Create and manage your event subscriptions
            read:integration: View your integrations
            write:integration: Connect and manage integrations
            read:invoice: View your invoices
            read:notification: View your notifications
            write:notification: Manage your notifications
            read:operational-settings: View your warehouses, shipping lanes, and other operational settings
            write:operational-settings: Manage your warehouses, shipping lanes, and other operational settings
            read:order: View your orders
            write:order: Import and process your orders
            read:organization: View organization settings
            write:organization: Change organization settings
            read:parcel: View your shipments and their tracking status
            write:parcel: Create, announce, and cancel shipments
            read:pickup: View carrier pickups and the options available for scheduling them
            write:pickup: Schedule and manage carrier pickups
            read:price: View shipping prices
            write:product: Manage your product catalog
            read:return: View your returns
            write:return: Create and manage returns
            read:return-settings: View your return settings
            write:return-settings: Configure your return settings
            read:service-point: View carrier service points
            read:shipping-method: View shipping methods, products and prices
            read:shipping-rule: View your shipping rules
            write:shipping-rule: Create and manage shipping rules
            read:support-ticket: View your support tickets
            write:support-ticket: Manage your support tickets
            read:tracking-message: View your tracking notifications
            write:tracking-message: Manage your tracking notifications
            read:tracking-page: View your tracking page
            write:tracking-page: Customize your tracking page
            read:user: Read your basic account information
  schemas:
    ShippingPrice:
      type: object
      description: Shipping price response
      properties:
        price:
          type: string
          description: Shipping price
          format: currency
          example: '6.50'
          nullable: true
        currency:
          type: string
          description: 3 letter currency code as defined by ISO-4217
          example: EUR
          format: iso-4217
          nullable: true
        to_country:
          type: string
          description: The receiver country of the shipment, as an [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
          example: NL
          format: iso 3166-1
        breakdown:
          $ref: '#/components/schemas/shipping-price-breakdown'
    Error:
      type: object
      description: Error response for shipping price
      properties:
        error:
          type: object
          properties:
            request:
              type: string
              format: uri-reference
              example: api/v2/shipping-price/
              description: The requested URL
            code:
              type: integer
              format: int32
              example: 400
              description: Code of the error
            message:
              type: string
              example: Bad request
              description: Description of the error
    shipping-price-breakdown:
      title: Shipping Price Breakdown Object
      description: A Sendcloud shipping price breakdown.
      type: array
      items:
        type: object
        properties:
          type:
            type: string
            example: price_without_insurance
            description: Type of the price. It is an identifier of category of the price.
          label:
            type: string
            example: Initial price per parcel
            description: This label is a friendly name for type of the price type and can be used to represent it.
          value:
            type: number
            format: float
            example: 6.4
            description: Price amount of the breakdown item.
  responses:
    '200':
      description: OK
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/ShippingPrice'
          examples:
            RetrieveShippingPrices:
              summary: Shipping prices
              $ref: '#/components/examples/ShippingPrice'
            NotPrices:
              summary: No prices available
              $ref: '#/components/examples/NoPrice'
            NoData:
              summary: No data available
              $ref: '#/components/examples/NoData'
    '400':
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            BadRequest:
              summary: Bad Request
              $ref: '#/components/examples/required_field_error'
  parameters:
    shipping_method_id:
      schema:
        type: integer
      in: query
      name: shipping_method_id
      description: The id of the shipping method retrieved via [shipping products](/api/v2/shipping-products/retrieve-a-list-of-shipping-products) or [shipping methods](/api/v2/shipping-methods/retrieve-a-list-of-shipping-methods).
      required: true
    from_country:
      schema:
        type: string
      in: query
      name: from_country
      description: The sender country of the shipment, as an [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
      required: true
    to_country:
      schema:
        type: string
      in: query
      name: to_country
      description: The receiver country of the shipment, as an [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). Required if the carrier is zonal. Also required to see if remote surcharges apply.
    weight:
      schema:
        type: integer
      in: query
      name: weight
      description: The weight of the shipment, in weight_unit.
      required: true
    weight_unit:
      schema:
        type: string
      in: query
      name: weight_unit
      description: One of `kilogram` or `gram`.
      required: true
    contract:
      name: contract
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        example: 123
      description: Id of the contract that you would like to use to get the price. If you are requesting price for a direct contract then you need to upload your own price via the Sendcloud platform.
    from_postal_code:
      name: from_postal_code
      in: query
      required: false
      schema:
        type: string
        maxLength: 12
        example: '01000'
      description: Postal code of the sender. Required if the carrier is zonal.
    to_postal_code:
      name: to_postal_code
      in: query
      required: false
      schema:
        type: string
        example: '01000'
        maxLength: 12
      description: Postal code of the recipient. Required if the carrier is zonal. Also required to see if remote surcharges apply.
  examples:
    ShippingPrice:
      summary: Shipping price
      value:
        - price: '6.50'
          currency: EUR
          to_country: NL
          breakdown:
            - type: price_without_insurance
              label: Label
              value: 6.5
    NoPrice:
      summary: No prices
      value:
        - price: null
          currency: null
          to_country: BE
    NoData:
      summary: No data
      value: []
    required_field_error:
      value:
        error:
          code: 400
          request: api/v2/shipping-price/
          message: 'shipping_method_id: "This field is required."'