Shipping rate quotes: quotes carrier rates for one lane.

POST /api/shipping/rate-quotes deprecated

Requires: Shipping.RateQuotes, merchant scope.

The quote runs through the merchant's own shipping provider binding. The request names a saved ship-from origin or supplies one inline, names saved parcel presets or supplies parcels inline, and gives the destination. The response carries the outcome and, on success, the rate options. A merchant with no enabled shipping provider receives the `NotConfigured` outcome rather than an error. Quotes are rate limited per merchant; a caller over the ceiling receives `Shipping:QuoteRateLimitExceeded` with HTTP 429.

Signed in, you can send this request to your own sandbox merchant from the console and read the answer. Sign in to try it.

Example request

Every block below sends the same request. Replace {{BASE_URL}} with the address of the API you are calling and {{API_KEY}} with your own key.

The request body is a ShippingRateQuoteRequestDto. See the Request body section below for its fields.

cURL PowerShell TypeScript C# Python

cURL

curl -X POST "{{BASE_URL}}/api/shipping/rate-quotes" \
  -H "api-key: {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
  "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "destination": {}
}'

PowerShell

$headers = @{
    'api-key' = '{{API_KEY}}'
}

$body = @'
{
  "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "destination": {}
}
'@

$response = Invoke-RestMethod -Method POST -Uri '{{BASE_URL}}/api/shipping/rate-quotes' `
    -Headers $headers -ContentType 'application/json' -Body $body

npm install @winkpg/winkpg-api

TypeScript (SDK)

import { Configuration, ShippingApi } from '@winkpg/winkpg-api';

const api = new ShippingApi(new Configuration({
  basePath: '{{BASE_URL}}',
  apiKey: '{{API_KEY}}',
}));

const { data } = await api.shippingRateQuoteGetQuote({
  "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "destination": {}
});

TypeScript (raw HTTP)

const response = await fetch('{{BASE_URL}}/api/shipping/rate-quotes', {
  method: 'POST',
  headers: {
    "api-key": "{{API_KEY}}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "destination": {}
  }),
});

const data = await response.json();

dotnet add package WinkPg.Api.Client

C# (SDK)

using WinkPg.Api.Client.Api;
using WinkPg.Api.Client.Client;
using System.Text.Json;

var config = new Configuration { BasePath = "{{BASE_URL}}" };
config.AddApiKey("api-key", "{{API_KEY}}");

var api = new ShippingApi(config);
var body = JsonSerializer.Deserialize<ShippingRateQuoteRequestDto>("""
    {
      "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "destination": {}
    }
    """);

var result = await api.ShippingRateQuoteGetQuoteAsync(body);

C# (raw HTTP)

using System.Text;

using var http = new HttpClient { BaseAddress = new Uri("{{BASE_URL}}") };

var request = new HttpRequestMessage(new HttpMethod("POST"), "/api/shipping/rate-quotes");
request.Headers.Add("api-key", "{{API_KEY}}");

request.Content = new StringContent("""
    {
      "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "destination": {}
    }
    """, Encoding.UTF8, "application/json");

var response = await http.SendAsync(request);
response.EnsureSuccessStatusCode();
var json = await response.Content.ReadAsStringAsync();

pip install winkpg-api

Python (SDK)

import winkpg_api

configuration = winkpg_api.Configuration(host="{{BASE_URL}}")
configuration.api_key["ApiKey"] = "{{API_KEY}}"

with winkpg_api.ApiClient(configuration) as client:
    api = winkpg_api.ShippingApi(client)
    body = winkpg_api.ShippingRateQuoteRequestDto.from_dict({
      "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "destination": {}
    })
    result = api.shipping_rate_quote_get_quote(body)

pip install requests

Python (raw HTTP)

import requests

headers = {
    "api-key": "{{API_KEY}}",
    "Content-Type": "application/json",
}

body = {
  "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "destination": {}
}

response = requests.request(
    "POST",
    "{{BASE_URL}}/api/shipping/rate-quotes",
    headers=headers,
    json=body,
)
response.raise_for_status()
data = response.json()

Parameters

Name	In	Type	Description
`suppressNulls` required	query	boolean	If true, omit properties with null values.

Request body

application/json , required

Field	Type	Description
`merchantId` required	string (uuid)	The merchant the quote is for. The caller must be authorized over this merchant; an API key quotes only for the merchant it belongs to. nullable
`originId` required	string (uuid)	The id of a saved ship-from origin belonging to the merchant. Give this or `origin`, not both. Conditional: When OriginId is not null. nullable
`origin` required	all of Address	A ship-from address supplied inline, for a quote from a location the merchant has not saved. Give this or `originId`, not both. Conditional: When Origin is not null.
`destination` required	all of Address	The address the parcels ship to.
`destinationIsResidential` required	boolean	Whether the destination is a residence. Some carriers price residential delivery differently; leave unset when unknown and the provider applies its own default. nullable
`parcelPresetIds` required	array of string (uuid)	The ids of saved parcel presets belonging to the merchant, one per parcel in the shipment. Give this or `parcels`, not both. nullable
`parcels` required	array of ShippingRateQuoteParcelDto	The parcels supplied inline, one per parcel in the shipment. Give this or `parcelPresetIds`, not both. nullable
`carriers` required	array of string	Optional provider-specific carrier account identifiers to restrict the quote to. When omitted the provider quotes every carrier the binding allows. nullable
`serviceLevels` required	array of string	Optional provider-specific service level tokens to restrict the quote to. When omitted the provider returns every service level the binding allows. nullable
`currency` required	string	The ISO 4217 currency the quotes should be expressed in. When omitted the platform's configured default currency is requested. Conditional: When Currency is not empty. nullable

This request body has no documented fields.