The Estimate resource allows a user to retrieve the estimated cost of shipping a package based on weight, dimensions, entry point, destination, and other parameters. No services will be returned if a route can't be matched against the provided parameters.
swagger: '2.0'
info:
x-logo:
url: https://storage.googleapis.com/boxc_cdn/public/boxc-logo.png
altText: BoxC
title: BoxC CalculateDuty Estimate API
version: '1.123'
description: 'A simple but powerful logistics API that drives international ecommerce by utilizing a single integration with access to dozens of carriers and global markets. BoxC can complete every leg or only select steps of a shipment''s journey on your behalf with our routing engine.
'
schemes:
- https
tags:
- name: Estimate
x-displayName: Estimate
description: The Estimate resource allows a user to retrieve the estimated cost of shipping a package based on weight, dimensions, entry point, destination, and other parameters. No services will be returned if a route can't be matched against the provided parameters.
paths:
/estimate:
get:
tags:
- Estimate
summary: GET /estimate
description: Retrieves an estimate.
operationId: getEstimate
consumes:
- application/json
produces:
- application/json
security:
- JWT: []
parameters:
- in: query
name: carrier
description: The preffered last mile carrier the shipment should use for delivery.
required: false
default: null
type: string
example: DHLeC
- in: query
name: country
description: The destination country in [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format.
required: true
minLength: 2
maxLength: 2
format:
- A-Z
type: string
example: US
- in: query
name: currency
description: The ISO 4217 currency code for the **value** parameter and rates that are returned.
required: false
default: USD
minLength: 3
maxLength: 3
format:
- A-Z
type: string
example: USD
- in: query
name: dg_codes
description: A string or array of [dangerous good codes](/#tag/DangerousGoods) contained in the shipment.
required: false
type: string|array
example: 0965
- in: query
name: entry_point
description: The code for the drop off location. See [Entry Points](/#tag/EntryPoints) for a list of codes.
required: true
type: string
example: LAXI01
minLength: 6
maxLength: 6
- in: query
name: exit_point
description: The IATA port where the shipment should enter for last mile delivery. Providing this limits results to only those routes with the matching port.
required: false
default: null
type: string
example: JFK
minLength: 3
maxLength: 3
- in: query
name: height
description: The height of the shipment in CM.
required: false
default: 1
type: decimal
example: 10.5
- in: query
name: insurance
description: By default all shipments except for BoxC Post include insurance covering up to $30 of the total item value including shipping cost. Setting this to true will increase the insured value for an additional fee.
required: false
default: false
type: boolean
example: true
- in: query
name: irregular
description: Indicates this shipment was packaged in irregular shaped polybag or soft packaging to assist in calculating the volumetric weight.
required: false
default: false
type: boolean
example: true
- in: query
name: is_return
description: Indicates this shipment is a return.
required: false
default: false
type: boolean
example: true
- in: query
name: length
description: The length of the shipment in CM.
required: false
default: 15
type: integer
example: 25
- in: query
name: packages
type: array
items:
$ref: '#/definitions/PackageEstimate'
maxItems: 12
default: []
- in: query
name: postal_code
description: The destination Postal Code or ZIP Code. Conditional.
required: false
type: string
example: 10128
maxLength: 10
- in: query
name: province
description: The destination province / state code. Conditional.
required: false
type: string
example: NY
maxLength: 40
- in: query
name: signature_confirmation
description: The shipment requires signature confirmation.
required: false
default: false
type: boolean
example: true
- in: query
name: terms
description: The preferred incoterms.
enum:
- DAP
- DDU
- DDP
required: false
default: null
type: string
example: DDU
- in: query
name: value
description: The total value of the items to calculate tax and insurance. Used with <i>currency</i>.
required: false
default: 0
type: decimal
example: 100
- in: query
name: weight
description: The weight of the shipment in KG.
required: true
exclusiveMinimum: 0
type: decimal
example: 0.345
- in: query
name: width
description: The width of the shipment in CM.
required: false
default: 10
type: integer
example: 2
x-codeSamples:
- lang: cURL
label: cURL
source: "curl -H \"Authorization: Bearer <YOUR TOKEN>\" \\\n -H \"Accept: application/json\" \\\n https://api.boxc.com/v1/estimate\\?entry_point=TEST01\\&weight=0.345\\&height=10.5\\&width=2\\&length=15\\&province=CA\\&postal_code=94041\\&country=US\\&signature_confirmation=false\\&value=100\\¤cy=CAD\\&irregular=0\\&insurance=true\\&carrier=DHLeC\\&is_return=false&packages[0][length]=10&packages[0][height]=5&packages[0][width]=15&packages[0][weight]=5&packages[1][length]=20&packages[1][height]=10&packages[1][width]=12&packages[1][weight]=4\n"
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/definitions/Estimate'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/definitions/BadRequest'
'401':
$ref: '#/definitions/Unauthorized'
'403':
$ref: '#/definitions/Forbidden'
'429':
$ref: '#/definitions/RateLimit'
definitions:
bad-request:
type: object
summary: Bad Request
description: Validation error with the request
properties:
code:
description: Error code. Refer to the list of [Errors](/#tag/Errors).
type: integer
message:
description: Error message explaining the code.
type: string
status:
type: string
enum:
- error
example: error
errors:
description: Lists validation errors with the schema or the resource being operated on.
type: array
minItems: 1
maxItems: 5
items:
type: string
package-estimate:
type: object
title: Package
properties:
height:
description: The height of the package in cm.
type: decimal
exclusiveMinimum: 0
exclusiveMaximum: 1000
example: 1
length:
description: The length of the package in cm.
type: decimal
exclusiveMinimum: 0
exclusiveMaximum: 1000
example: 15
weight:
description: The weight of the package in kg.
type: decimal
exclusiveMinimum: 0
exclusiveMaximum: 1000
example: 15
width:
description: The width of the package in cm.
type: decimal
exclusiveMinimum: 0
exclusiveMaximum: 1000
example: 10
required:
- height
- length
- weight
- width
Estimate:
$ref: '#/definitions/estimate'
service:
type: object
description: A list of services and their estimated price and transit time. Set by the system. If an empty array is returned then there are currently no services available for the given route.
properties:
carrier:
description: The last mile carrier the shipment will use for delivery.
type: string
example: USPS
chargeable_weight:
description: The greater of the gross weight and volumetric weight.
type: decimal
example: 0.412
cost:
description: The estimated shipping cost.
type: decimal
example: 3.55
exit_point:
description: The destination port the shipment will be transported to before last mile delivery.
type: string
default: null
example: LAX
gross_weight:
description: The greater of the requested weight and minimum gross weight for the route.
type: decimal
example: 0.25
insurance:
type: object
description: Insurance details for this service.
properties:
coverage:
type: decimal
description: The dollar amount covered by the insurance policy.
example: 30
fee:
type: decimal
description: The cost of coverage if insured.
example: 0
service:
type: string
description: Service name
example: BoxC Priority
surcharge:
description: Additional cost for this shipment based on the route and chargeable weight.
type: decimal
example: 0.75
terms:
type: array
description: Acceptable incoterms for this route.
items:
type: string
example:
- DAP
- DDU
- DDP
total_cost:
description: The total estimated shipping cost including applicable fees.
type: decimal
example: 3.55
transit_min:
type: integer
description: Estimated minimum transit time in days.
example: 5
transit_max:
type: integer
description: Estimated maximum transit time in days.
example: 10
volumetric_weight:
description: The volumetric weight based on the requested dimensions and route's divisor.
type: decimal
example: 0.412
Service:
$ref: '#/definitions/service'
BadRequest:
$ref: '#/definitions/bad-request'
unauthorized:
description: Unauthorized
content:
application/json:
schema:
type: object
summary: Unauthorized
description: Lack of valid authentication credentials for the resource
properties:
code:
description: Error code. Refer to the list of [Errors](/#tag/Errors).
type: integer
message:
description: Error message explaining the code.
type: string
status:
type: string
enum:
- error
example: error
errors:
description: Displays processing error.
type: array
minItems: 1
maxItems: 1
items:
type: string
examples:
accessToken:
summary: Invalid access token
description: Invalid access token
value:
code: 1005
message: Invalid access token
errors:
- Invalid access token
RateLimit:
$ref: '#/definitions/rate-limit'
rate-limit:
description: Too Many Requests
content:
application/json:
schema:
type: object
summary: Too Many Requests
description: Error for too many requests in a given time frame. See [Rate Limits](/#tag/RateLimit) for more information.
properties:
code:
description: Error code. Refer to the list of [Errors](/#tag/Errors).
type: integer
message:
description: Error message explaining the code.
type: string
status:
type: string
enum:
- error
example: error
errors:
description: Displays processing error.
type: array
minItems: 1
maxItems: 1
items:
type: string
examples:
rateLimit:
summary: Too Many Requests
description: Too many requests. Please wait before trying again.
value:
code: 1015
message: Too many requests. Please wait before trying again.
errors:
- Too many requests. Please wait before trying again.
Forbidden:
$ref: '#/definitions/forbidden'
Unauthorized:
$ref: '#/definitions/unauthorized'
estimate:
type: object
description: Retrieves an estimate.
properties:
estimate:
type: object
properties:
currency:
description: The ISO 4217 currency code for the **value** parameter and rates that are returned.
type: string
example: CAD
readOnly: true
entry_point:
description: The code for the drop off location. See [Entry Points](/#tag/EntryPoints) for a list of codes.
type: string
default: null
example: LAXI01
readOnly: true
services:
type: array
readOnly: true
items:
$ref: '#/definitions/Service'
PackageEstimate:
$ref: '#/definitions/package-estimate'
forbidden:
description: Forbidden
content:
application/json:
schema:
type: object
summary: Forbidden
description: Error relating to insufficient permissions for a resource
properties:
code:
description: Error code. Refer to the list of [Errors](/#tag/Errors).
type: integer
message:
description: Error message explaining the code.
type: string
status:
type: string
enum:
- error
example: error
errors:
description: Displays processing error.
type: array
minItems: 1
maxItems: 1
items:
type: string
examples:
revoked:
summary: Forbidden Authorization Revoked
description: 'Forbidden: Authorization revoked'
value:
code: 1008
message: 'Forbidden: Authorization revoked'
errors:
- 'Forbidden: Authorization revoked'
scope:
summary: Forbidden Scope
description: 'Forbidden: Missing required scope'
value:
code: 1009
message: 'Forbidden: Missing required scope'
errors:
- 'Forbidden: Missing required scope'
securityDefinitions:
JWT:
type: http
scheme: bearer
bearerScheme: JWT
in: header
description: All operations require a JSON Web Token after completing an [OAuth2 flow](#tag/Authentication).
PrivilegedClient:
type: http
scheme: bearer
bearerScheme: JWT
description: Some clients require special privileges to use operations. No additional scope is needed.
x-servers:
- url: https://api.boxc.com/v1
x-tagGroups:
- name: Overview
tags:
- Introduction
- Authentication
- RateLimit
- Paginate
- Changelog
- name: Operations
tags:
- CalculateDuty
- Classify
- Invoices
- Users
- ValidateAddress
- Webhooks
- name: Shipping
tags:
- Credentials
- CustomsProducts
- EntryPoints
- Estimate
- Labels
- Manifests
- Overpacks
- Shipments
- Track
- name: Fulfillment
tags:
- Inbound
- Orders
- Products
- Shops
- Warehouses
- name: Returns
tags:
- Reshipments
- Returns
- name: Data
tags:
- CarrierCredentials
- DangerousGoods
- Errors
- Languages
- CarrierParameters
- ReturnsProcess
- TrackingEvents