Get shipping rates

note

The channelCode and warehouseCode in the example are placeholders — use real values from your context — and the carrier, service and price in the response are examples: you will see the rates configured for your channel. Channel codes are provided by Calicantus during onboarding: if you do not have yours, contact developers@calicant.us.

Use shippingRates query to retrieve the available carrier rates for a shipment, given the origin warehouse, the sales channel, the recipient address, the declared value, and the parcels. The query accepts a ShippingRatesValueInput, a ShippingRatesRecipientAddressInput and a list of ShippingRatesParcelInput objects — their references list all the available fields.

The query does not require an existing order or shipment, so you can call it whenever you need to know the shipping cost in advance. Typical scenarios:

• E-commerce checkout — show the customer the real shipping cost (and the available service options, e.g. standard vs express) for their cart before they confirm the order.
• Carrier selection — compare the available rates and pick the cheapest or fastest service before creating the shipment.
• Quotes and customer care — estimate the shipping cost of a prospective order, for example when preparing a quote or answering a customer inquiry.
• Destination coverage check — verify that at least one carrier serves the recipient address with the given parcels: an empty result means no rate is available for that shipment (see No rates available — and how it differs from an unknown channel or warehouse code).

Field notes:

• channelCode is the sales channel code and warehouseCode is the origin warehouse code — list your warehouse codes with the warehouses query.
• value is the declared value of the shipment: amount and currency.
• recipientAddress requires address1, city, isoCountry and zipCode; the other address fields are optional.
• parcels: each parcel requires kind (box or pallet), dimensions in centimeters and net weight in grams (e.g. weight: 5000 is 5 kg).

Example

In this example we request the rates for a single parcel shipped to an Italian address. The response lists each available carrier rate with its service and price.

Request

query shippingRates {
  shippingRates(
    channelCode: "ECOM"
    warehouseCode: "MIL"
    value: { amount: 250.0, currency: "EUR" }
    recipientAddress: {
      address1: "Via Roma 1"
      city: "Milano"
      isoCountry: "IT"
      zipCode: "20100"
    }
    parcels: [
      # dimensions in cm, net weight in grams (5000 g = 5 kg)
      { kind: box, length: 40, width: 30, height: 20, weight: 5000 }
    ]
  ) {
    carrier {
      code
      name
    }
    service {
      name
    }
    price {
      amount
      currency
    }
  }
}

Open in playground

Response

{
  "data": {
    "shippingRates": [
      {
        "carrier": { "code": "TNT", "name": "TNT" },
        "service": { "name": "Express" },
        "price": { "amount": 9.41, "currency": "EUR" }
      }
    ]
  },
  "extensions": {
    "queryComplexity": 9,
    "bucketBalance": 9991,
    "bucketRestoreRate": 100
  }
}

No rates available

When no carrier rate is available for the requested shipment, shippingRates returns an empty array (this is a valid, successful response, not an error):

{
  "data": {
    "shippingRates": []
  },
  "extensions": {
    "queryComplexity": 9,
    "bucketBalance": 9991,
    "bucketRestoreRate": 100
  }
}

An unknown channelCode or warehouseCode is a different case: the query fails with the error code NOT_FOUND (see Errors). Check your codes before concluding that no carrier serves the destination:

{
  "errors": [
    {
      "message": "Record not found.",
      "locations": [{ "line": 2, "column": 3 }],
      "path": ["shippingRates"],
      "extensions": { "code": "NOT_FOUND" }
    }
  ],
  "data": {
    "shippingRates": null
  },
  "extensions": {
    "queryComplexity": 9,
    "bucketBalance": 9991,
    "bucketRestoreRate": 100
  }
}

Relevant permissions

The operations in this page require the following permissions on the API credentials — they are configured for you by Calicantus.

• shipping_rate:query:shipping_rates
• shipping_rate:read