Skip to content

Calculate shipping options

POST
/stores/{storeRef}/shipping/calculate
curl --request POST \
--url https://apibase.ecomweb.app/api/v1/stores/example/shipping/calculate \
--header 'Content-Type: application/json' \
--header 'x-api-key: <x-api-key>' \
--data '{ "province_id": "01", "ward_id": "00001", "postal_code": "700000", "subtotal": 320000, "currency": "VND", "weight_gr": 1800, "include_carrier_options": false }'

Works out which of the store’s shipping zones covers an address and returns the options available for an order of the given value and weight. Unlike the storefront calculation, each option also carries the winning zone (zone_id, zone_name) and the zones it shadowed, so you can see why a fee applies. Carrier-calculated options are added only when include_carrier_options is true, which contacts the AllinGo carrier live; prices from a carrier account in test mode are left out. Unlike most POST routes, it answers 201 although it creates nothing.

Required scopes: read:shippings

storeRef
required
string

The store’s ref, as returned by GET /stores.

Media typeapplication/json
object
province_id

Province code/ID (preferred over province name)

string

Example

01
ward_id

Ward code/ID (preferred over district name)

string

Example

00001
postal_code
string

Example

700000
subtotal
required

Order subtotal in smallest unit

number

Example

320000
currency
required

Currency code

string

Example

VND
weight_gr
required

Total weight in grams

number

Example

1800
include_carrier_options

Also return live carrier-calculated options (AllinGo). Defaults to false: callers that key options by rate_id keep getting fixed rates only.

boolean

Example

false
Media typeapplication/json
Array<object>
object
carrier_code

Carrier options only: the carrier, allingo.

string
Allowed values: allingo
option_id
required

<rate_id> for a fixed option, <rate_id>:<service_id> for a carrier option.

string
amount
required

Shipping fee.

number
currency
required

ISO 4217 currency code.

string
rate_id
required

ID of the rate the option comes from.

number
delivery_type
required

Kind of delivery, such as STANDARD or EXPRESS.

string
display_name
required

Name to show the shopper.

string
estimated_days_min

Fastest estimated delivery in days, or null.

number
nullable
estimated_days_max

Slowest estimated delivery in days, or null.

number
nullable
zone_id

ID of the zone that won address resolution.

number
zone_name

Name of the zone that won address resolution.

string
shadowed_zones

Zones that also matched the address but lost to zone_id.

Array<object>
object
id
required

Zone ID.

number
name
required

Zone name.

string
rank
required

Rank of the zone in address resolution.

number
carrier_service_id

Carrier options only: ID of the carrier service. Send it back as shipping_service_id when placing the order.

string
carrier_name

Carrier options only: name of the delivery partner, such as GHN.

string
carrier_service_name

Carrier options only: name of the partner’s service.

string
carrier_logo_url

Carrier options only: logo URL of the delivery partner, or null.

string
nullable
estimated_label

Carrier options only: estimated delivery time as a label, or null.

string
nullable

Example

[
{
"carrier_code": "allingo"
}
]

The request is malformed or failed validation.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}

The key is missing, invalid, revoked or expired.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}

The key may not do this: a missing scope, a readonly key, a publishable key on a Store API route, or a disallowed origin.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}