Skip to content

Calculate shipping fees

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

Returns the shipping options for an address and an order, worked out from the store’s shipping zones and rates, one option per delivery type. Send province_id and ward_id, the codes from the areas route, the order subtotal and the total weight in grams. Set include_carrier_options to also get live quotes from the delivery partner. Nothing is created or reserved.

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

The shipping options that apply, one per delivery type.

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
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"
}