openapi: 3.0.0
info:
title: ShipEngine API
version: 1.1.202405011605
termsOfService: 'https://www.shipengine.com/terms-of-service/'
x-logo:
url: 'https://shipengine.github.io/img/shipengine-logo-square.png'
backgroundColor: '#FFFFFF'
altText: ShipEngine logo
contact:
name: ShipEngine Sales & Support
email: sales@shipengine.com
url: 'https://www.shipengine.com/contact/'
x-phone: 1-512-856-5379
description: >
ShipEngine's easy-to-use REST API lets you manage all of your shipping needs
without worrying about the complexities of different carrier APIs and
protocols. We handle all the heavy lifting so you can focus on providing a
first-class shipping experience for your customers at the best possible
prices.
Each of ShipEngine's features can be used by itself or in conjunction with
each other to build powerful shipping functionality into your application or
service.
## Getting Started
If you're new to REST APIs then be sure to read our [introduction to
REST](https://www.shipengine.com/docs/rest/) to understand the basics.
Learn how to [authenticate yourself to
ShipEngine](https://www.shipengine.com/docs/auth/), and then use our
[sandbox environment](https://www.shipengine.com/docs/sandbox/) to kick the
tires and get familiar with our API. If you run into any problems, then be
sure to check the [error handling
guide](https://www.shipengine.com/docs/errors/) for tips.
Here are some step-by-step **tutorials** to get you started:
- [Learn how to create your first shipping label](https://www.shipengine.com/docs/labels/create-a-label/)
- [Calculate shipping costs and compare rates across carriers](https://www.shipengine.com/docs/rates/)
- [Track packages on-demand or in real time](https://www.shipengine.com/docs/tracking/)
- [Validate mailing addresses anywhere on Earth](https://www.shipengine.com/docs/addresses/validation/)
## Shipping Labels for Every Major Carrier
ShipEngine makes it easy to [create shipping labels for any
carrier](https://www.shipengine.com/docs/labels/create-a-label/) and
[download them](https://www.shipengine.com/docs/labels/downloading/) in a
[variety of file formats](https://www.shipengine.com/docs/labels/formats/).
You can even customize labels with your own
[messages](https://www.shipengine.com/docs/labels/messages/) and
[images](https://www.shipengine.com/docs/labels/branding/).
## Real-Time Package Tracking
With ShipEngine you can [get the current status of a
package](https://www.shipengine.com/docs/tracking/) or [subscribe to
real-time tracking
updates](https://www.shipengine.com/docs/tracking/webhooks/) via webhooks.
You can also create [custimized tracking
pages](https://www.shipengine.com/docs/tracking/branded-tracking-page/) with
your own branding so your customers will always know where their package is.
## Compare Shipping Costs Across Carriers
Make sure you ship as cost-effectively as possible by [comparing rates
across carriers](https://www.shipengine.com/docs/rates/get-shipment-rates/)
using the ShipEngine Rates API. Or if you don't know the full shipment
details yet, then you can [get rate
estimates](https://www.shipengine.com/docs/rates/estimate/) with limited
address info.
## Worldwide Address Validation
ShipEngine supports [address
validation](https://www.shipengine.com/docs/addresses/validation/) for
virtually [every country on
Earth](https://www.shipengine.com/docs/addresses/validation/countries/),
including the United States, Canada, Great Britain, Australia, Germany,
France, Norway, Spain, Sweden, Israel, Italy, and over 160 others.
paths:
/v1/account/settings:
summary: Account settings
description: ShipEngine Account settings
get:
summary: List Account Settings
description: List all account settings for the ShipEngine account
tags:
- account
operationId: list_account_settings
responses:
'200':
description: The request was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/get_account_settings_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
/v1/account/settings/images:
summary: Account settings images
description: ShipEngine Account images
get:
summary: List Account Images
description: List all account images for the ShipEngine account
tags:
- account
operationId: list_account_images
responses:
'200':
description: The request was a success.
content:
application/json:
schema:
$ref: >-
#/components/schemas/list_account_settings_images_response_body
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
post:
summary: Create an Account Image
description: Create an Account Image
tags:
- account
operationId: create_account_image
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/create_account_settings_image_request_body'
responses:
'200':
description: The requested object creation was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/get_account_settings_images_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
'/v1/account/settings/images/{label_image_id}':
summary: Account settings images
description: ShipEngine Account images
get:
summary: Get Account Image By ID
description: Retrieve information for an account image.
tags:
- account
operationId: get_account_settings_images_by_id
parameters:
- name: label_image_id
in: path
required: true
schema:
$ref: '#/components/schemas/image_id'
description: Label Image Id
responses:
'200':
description: The request was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/get_account_settings_images_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
put:
summary: Update Account Image By ID
description: Update information for an account image.
tags:
- account
operationId: update_account_settings_images_by_id
parameters:
- name: label_image_id
in: path
required: true
schema:
$ref: '#/components/schemas/image_id'
description: Label Image Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/update_account_settings_image_request_body'
responses:
'204':
description: The request was successful.
content:
text/plain:
schema:
$ref: '#/components/schemas/empty_response_body'
application/json:
schema:
$ref: '#/components/schemas/empty_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
delete:
summary: Delete Account Image By Id
description: Delete Account Image By Id
tags:
- account
operationId: delete_account_image_by_id
parameters:
- name: label_image_id
in: path
required: true
schema:
$ref: '#/components/schemas/image_id'
description: Label Image Id
responses:
'204':
description: The request was successful.
content:
text/plain:
schema:
$ref: '#/components/schemas/empty_response_body'
application/json:
schema:
$ref: '#/components/schemas/empty_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
/v1/addresses/recognize:
summary: Parse an address
description: >
Data often enters your system as unstructured text (for example: emails,
SMS messages, support tickets, or other documents). ShipEngine's
address-recognition API helps you extract meaningful address data (e.g.
recipient name, address line 1, line 2, city, postal code) from this
unstructured text.
put:
summary: Parse an address
description: >
The address-recognition API makes it easy for you to extract address
data from unstructured text, including the recipient name, line 1, line
2, city, postal code, and more.
Data often enters your system as unstructured text (for example: emails,
SMS messages, support tickets, or other documents). ShipEngine's
address-recognition API helps you extract meaningful, structured data
from this unstructured text. The parsed address data is returned in the
same structure that's used for other ShipEngine APIs, such as address
validation, rate quotes, and shipping labels.
> **Note:** Address recognition is currently supported for the United
States, Canada, Australia, New Zealand, the United Kingdom, and Ireland.
tags:
- addresses
operationId: parse_address
requestBody:
required: true
description: >
The only required field is `text`, which is the text to be parsed. You
can optionally also provide an `address` containing already-known
values. For example, you may already know the recipient's name, city,
and country, and only want to parse the street address into separate
lines.
content:
application/json:
schema:
$ref: '#/components/schemas/parse_address_request_body'
examples:
text_only:
summary: Text only
description: >
This is the simplest way to call the address-recognition API.
Just pass the text to be parsed and nothing else.
value:
text: >-
Margie McMiller at 3800 North Lamar suite 200 in austin,
tx. The zip code there is 78652.
some_known_fields:
summary: Some known fields
description: >
You can optionally provide an `address` object containing any
already-known values. For example, you may already know the
recipient's name, city, and country, and only want to parse
the street address into separate lines.
value:
text: >-
Margie McMiller at 3800 North Lamar suite 200 in austin,
tx. The zip code there is 78652.
address:
country_code: US
address_residential_indicator: 'yes'
responses:
'200':
description: >
Returns the parsed address, as well as a confidence score and a list
of all the entities that were recognized in the text.
content:
application/json:
schema:
$ref: '#/components/schemas/parse_address_response_body'
examples:
text_only:
description: >
This response shows that the address-recognition API was
able to recognize all the address entities in the text.
Notice that the `country_code` is not populated and the
`address_residential_indicator` is "unknown", since neither
of these fields was included in the text.
value:
score: 0.9122137426845613
address:
name: Margie McMiller
address_line1: 3800 North Lamar
address_line2: Suite 200
city_locality: Austin
state_province: TX
postal_code: 78652
address_residential_indicator: unknown
entities:
- type: person
score: 0.9519646137063122
text: Margie McMiller
start_index: 0
end_index: 14
result:
value: Margie McMiller
- type: address_line
score: 0.9805313966503588
text: 3800 North Lamar
start_index: 19
end_index: 34
result:
line: 1
value: 3800 North Lamar
- type: number
score: 0.9805313966503588
text: 3800
start_index: 19
end_index: 22
result:
type: cardinal
value: 3800
- type: address_line
score: 1
text: suite 200
start_index: 36
end_index: 44
result:
line: 2
value: Suite 200
- type: number
score: 0.9805313966503588
text: 200
start_index: 42
end_index: 44
result:
type: cardinal
value: 200
- type: city_locality
score: 0.9805313966503588
text: austin
start_index: 49
end_index: 54
result:
value: Austin
- type: state_province
score: 0.6082904353940255
text: tx
start_index: 57
end_index: 58
result:
name: Texas
value: TX
- type: postal_code
score: 0.9519646137063122
text: 78652
start_index: 84
end_index: 88
result:
value: 78652
some_known_fields:
description: >
This response is shows that the address-recognition API was
able to recognize all the address entities in the text.
Notice that the `country_code` and
`address_residential_indicator` fields are populated with
the values that were provided in the request.
value:
score: 0.9122137426845613
address:
name: Margie McMiller
address_line1: 3800 North Lamar
address_line2: Suite 200
city_locality: Austin
state_province: TX
postal_code: 78652
country_code: US
address_residential_indicator: 'yes'
entities:
- type: person
score: 0.9519646137063122
text: Margie McMiller
start_index: 0
end_index: 14
result:
value: Margie McMiller
- type: address_line
score: 0.9805313966503588
text: 3800 North Lamar
start_index: 19
end_index: 34
result:
line: 1
value: 3800 North Lamar
- type: number
score: 0.9805313966503588
text: 3800
start_index: 19
end_index: 22
result:
type: cardinal
value: 3800
- type: address_line
score: 1
text: suite 200
start_index: 36
end_index: 44
result:
line: 2
value: Suite 200
- type: number
score: 0.9805313966503588
text: 200
start_index: 42
end_index: 44
result:
type: cardinal
value: 200
- type: city_locality
score: 0.9805313966503588
text: austin
start_index: 49
end_index: 54
result:
value: Austin
- type: state_province
score: 0.6082904353940255
text: tx
start_index: 57
end_index: 58
result:
name: Texas
value: TX
- type: postal_code
score: 0.9519646137063122
text: 78652
start_index: 84
end_index: 88
result:
value: 78652
'400':
$ref: '#/components/responses/400_error_response'
'500':
$ref: '#/components/responses/500_error_response'
/v1/addresses/validate:
summary: Address Validation
description: >
Address validation ensures accurate addresses and can lead to reduced
shipping costs by preventing address correction surcharges.
ShipEngine cross references multiple databases to validate addresses and
identify potential deliverability issues.
post:
summary: Validate An Address
description: >
Address validation ensures accurate addresses and can lead to reduced
shipping costs by preventing address correction surcharges.
ShipEngine cross references multiple databases to validate addresses and
identify potential deliverability issues.
tags:
- addresses
operationId: validate_address
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/validate_address_request_body'
examples:
all_known_fields_request:
summary: All Known Fields
description: A call that returns a status of `verified`.
value:
- name: Mickey and Minnie Mouse
phone: 714-781-4565
company_name: The Walt Disney Company
address_line1: 500 South Buena Vista Street
city_locality: Burbank
state_province: CA
postal_code: 91521
country_code: US
responses:
'200':
description: The request was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/validate_address_response_body'
examples:
all_known_fields:
summary: All Known Fields
description: A response for a `verified` status call.
value:
- status: verified
original_address:
name: Mickey and Minnie Mouse
phone: 714-781-4565
company_name: The Walt Disney Company
address_line1: 500 South Buena Vista Street
address_line2: null
address_line3: null
city_locality: Burbank
state_province: CA
postal_code: 91521
country_code: US
address_residential_indicator: unknown
matched_address:
name: MICKEY AND MINNIE MOUSE
phone: 714-781-4565
company_name: THE WALT DISNEY COMPANY
address_line1: 500 S BUENA VISTA ST
address_line2: null
address_line3: null
city_locality: BURBANK
state_province: CA
postal_code: 91521-0007
country_code: US
address_residential_indicator: 'no'
messages: []
empty_fields:
summary: Empty Fields
description: A response for an `unverified` API Call with error message
value:
- status: unverified
original_address:
name: null
phone: null
company_name: null
address_line1: null
address_line2: null
address_line3: null
city_locality: null
state_province: null
postal_code: null
country_code: null
address_residential_indicator: unknown
matched_address: null
messages:
- code: a1001
message: >-
country_code is not currently a supported country
please check the documentation for acceptable
2-letter country codes.
type: error
detail_code: unsupported_country
'400':
$ref: '#/components/responses/400_error_response'
'500':
$ref: '#/components/responses/500_error_response'
/v1/batches:
summary: Batches
description: >
Batches are an advanced feature of ShipEngine designed for users who need
to generate hundreds or thousands of labels at a time.
When ShipEngine generates labels it relies on many carriers, their
services, their dependencies, and a number of other variables
to fulfill your requests; those requests can take a few minutes for us to
get back to you.
get:
summary: List Batches
description: List Batches associated with your Shipengine account
operationId: list_batches
tags:
- batches
parameters:
- name: status
in: query
required: false
schema:
$ref: '#/components/schemas/batch_status'
- name: page
in: query
required: false
schema:
type: integer
format: int32
minimum: 1
default: 1
example: 2
description: >
Return a specific page of results. Defaults to the first page. If
set to a number that's greater than the number of pages of results,
an empty page is returned.
- name: page_size
in: query
required: false
schema:
type: integer
format: int32
minimum: 1
default: 25
example: 50
description: The number of results to return per response.
- name: sort_dir
in: query
required: false
schema:
allOf:
- $ref: '#/components/schemas/sort_dir'
default: desc
description: Controls the sort order of the query.
- name: batch_number
in: query
required: false
schema:
type: string
description: Batch Number
- name: sort_by
in: query
required: false
schema:
$ref: '#/components/schemas/batches_sort_by'
responses:
'200':
description: The request was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/list_batches_response_body'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
post:
summary: Create A Batch
description: Create a Batch
tags:
- batches
operationId: create_batch
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/create_batch_request'
responses:
'200':
description: The requested object creation was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/create_batch_response_body'
'207':
description: >-
The request was a partial success. It contains results, as well as
processing errors.
content:
application/json:
schema:
$ref: '#/components/schemas/create_batch_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'500':
$ref: '#/components/responses/500_error_response'
'/v1/batches/external_batch_id/{external_batch_id}':
summary: External Batch ID
description: Retrive a batch from an external batch ID
parameters:
- name: external_batch_id
in: path
required: true
schema:
type: string
example: 13553d7f-3c87-4771-bae1-c49bacef11cb
get:
summary: Get Batch By External ID
description: Get Batch By External ID
tags:
- batches
operationId: get_batch_by_external_id
responses:
'200':
description: The request was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/get_batch_by_external_id_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
'/v1/batches/{batch_id}':
summary: Batch By ID
description: Check the status of your batch by retrieving it with a Batch ID.
parameters:
- name: batch_id
in: path
required: true
schema:
$ref: '#/components/schemas/se_id'
description: Batch ID
delete:
summary: Delete Batch By Id
description: Delete Batch By Id
operationId: delete_batch
tags:
- batches
responses:
'204':
description: The request was successful.
content:
text/plain:
schema:
$ref: '#/components/schemas/empty_response_body'
application/json:
schema:
$ref: '#/components/schemas/empty_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
get:
summary: Get Batch By ID
description: Get Batch By ID
tags:
- batches
operationId: get_batch_by_id
responses:
'200':
description: The request was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/get_batch_by_id_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
put:
summary: Update Batch By Id
description: Update Batch By Id
operationId: update_batch
tags:
- batches
responses:
'204':
description: The request was successful.
content:
text/plain:
schema:
$ref: '#/components/schemas/empty_response_body'
application/json:
schema:
$ref: '#/components/schemas/empty_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
'/v1/batches/{batch_id}/add':
summary: Add Funds to a Carrier
description: >
You can check your balance for a particular carrier by calling [List
Carriers](https://www.shipengine.com/docs/reference/list-carriers/)
endpoint.
For any carrier account where requires_funded_amount is true, you can add
funds.
parameters:
- name: batch_id
in: path
required: true
schema:
$ref: '#/components/schemas/se_id'
description: Batch ID
post:
summary: Add to a Batch
description: Add a Shipment or Rate to a Batch
tags:
- batches
operationId: add_to_batch
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/add_to_batch_request_body'
responses:
'204':
description: The request was successful.
content:
text/plain:
schema:
$ref: '#/components/schemas/empty_response_body'
application/json:
schema:
$ref: '#/components/schemas/empty_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
'/v1/batches/{batch_id}/errors':
summary: Batch Errors
description: >
Error handling in batches are handled differently than in a single
synchronous request.
You must retrieve the status of your batch by [getting a
batch](https://www.shipengine.com/docs/reference/get-batch-by-id/) and
getting an overview of the statuses or you can list errors directly here
below to get detailed information about the errors.
parameters:
- name: batch_id
in: path
required: true
schema:
$ref: '#/components/schemas/se_id'
description: Batch ID
get:
summary: Get Batch Errors
description: >
Error handling in batches are handled differently than in a single
synchronous request.
You must retrieve the status of your batch by [getting a
batch](https://www.shipengine.com/docs/reference/get-batch-by-id/) and
getting an overview of the statuses or you can list errors directly here
below to get detailed information about the errors.
tags:
- batches
operationId: list_batch_errors
parameters:
- name: page
in: query
required: false
schema:
type: integer
format: int32
minimum: 1
default: 1
example: 2
description: >
Return a specific page of results. Defaults to the first page. If
set to a number that's greater than the number of pages of results,
an empty page is returned.
- name: pagesize
in: query
required: false
schema:
type: integer
format: int32
minimum: 1
responses:
'200':
description: The request was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/list_batch_errors_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
'/v1/batches/{batch_id}/process/labels':
summary: Process Batch ID Labels
description: Process Batch ID Labels
parameters:
- name: batch_id
in: path
required: true
schema:
$ref: '#/components/schemas/se_id'
description: Batch ID
post:
summary: Process Batch ID Labels
description: Process Batch ID Labels
tags:
- batches
operationId: process_batch
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/process_batch_request_body'
responses:
'204':
description: The request was successful.
content:
text/plain:
schema:
$ref: '#/components/schemas/empty_response_body'
application/json:
schema:
$ref: '#/components/schemas/empty_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
'/v1/batches/{batch_id}/remove':
summary: Remove Batch By ID
description: Remove a list of shipments from a batch
parameters:
- name: batch_id
in: path
required: true
schema:
$ref: '#/components/schemas/se_id'
description: Batch ID
post:
summary: Remove From Batch
description: Remove a shipment or rate from a batch
tags:
- batches
operationId: remove_from_batch
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/remove_from_batch_request_body'
responses:
'204':
description: The request was successful.
content:
text/plain:
schema:
$ref: '#/components/schemas/empty_response_body'
application/json:
schema:
$ref: '#/components/schemas/empty_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
/v1/carriers:
summary: Carriers
description: >
Carriers are a company or individual that specializes in transporting
freight from one destination to another.
Shipengine allows you to easily integrate with multiple carriers so you
can chose the shipping option that is right for you.
get:
summary: List Carriers
description: List all carriers that have been added to this account
tags:
- carriers
operationId: list_carriers
responses:
'200':
description: The request was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/get_carriers_response_body'
'207':
description: >-
The request was a partial success. It contains results, as well as
errors.
content:
application/json:
schema:
$ref: '#/components/schemas/get_carriers_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
'/v1/carriers/{carrier_id}':
summary: Individual carriers
description: >-
Perform actions and get information on individual carriers connected with
your account.
parameters:
- name: carrier_id
in: path
required: true
schema:
$ref: '#/components/schemas/se_id'
example: se-28529731
description: Carrier ID
get:
summary: Get Carrier By ID
description: Retrive carrier info by ID
tags:
- carriers
operationId: get_carrier_by_id
responses:
'200':
description: The request was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/get_carrier_by_id_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
delete:
summary: Disconnect Carrier by ID
description: Disconnect a Carrier of the given ID from the account
tags:
- carriers
operationId: disconnect_carrier_by_id
responses:
'204':
description: The request was successful.
content:
text/plain:
schema:
$ref: '#/components/schemas/empty_response_body'
application/json:
schema:
$ref: '#/components/schemas/empty_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
'/v1/carriers/{carrier_id}/add_funds':
summary: Carrier Funds
description: >-
All carriers require that funds to be attached to an account to ensure
payment for the various services they provide to their customers.
parameters:
- name: carrier_id
in: path
required: true
schema:
$ref: '#/components/schemas/se_id'
example: se-28529731
description: Carrier ID
put:
summary: Add Funds To Carrier
description: Add Funds To A Carrier
tags:
- carriers
operationId: add_funds_to_carrier
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/add_funds_to_carrier_request_body'
responses:
'200':
description: The request was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/add_funds_to_carrier_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
'/v1/carriers/{carrier_id}/options':
summary: Carrier Options
description: >-
Carriers support various options for particular shipments. Ex.
(non-machinable, is_alcohol, fragile, etc)
parameters:
- name: carrier_id
in: path
required: true
schema:
$ref: '#/components/schemas/se_id'
example: se-28529731
description: Carrier ID
get:
summary: Get Carrier Options
description: Get a list of the options available for the carrier
tags:
- carriers
operationId: get_carrier_options
responses:
'200':
description: The request was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/get_carrier_options_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
'/v1/carriers/{carrier_id}/packages':
summary: Carrier Packages
description: >
Carriers support many different package types, Shipengine supports
retrieving all available package so that
you can best determine what is right for your particular shipment.
parameters:
- name: carrier_id
in: path
required: true
schema:
$ref: '#/components/schemas/se_id'
example: se-28529731
description: Carrier ID
get:
summary: List Carrier Package Types
description: List the package types associated with the carrier
tags:
- carriers
operationId: list_carrier_package_types
responses:
'200':
description: The request was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/list_carrier_package_types_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
'/v1/carriers/{carrier_id}/services':
summary: Carrier Services
description: >
Carrier services usually refer to the various shipping options that a
carrier provides to its customers.
Ex. Priority mail, overnight, international
parameters:
- name: carrier_id
in: path
required: true
schema:
$ref: '#/components/schemas/se_id'
example: se-28529731
description: Carrier ID
get:
summary: List Carrier Services
description: List the services associated with the carrier ID
tags:
- carriers
operationId: list_carrier_services
responses:
'200':
description: The request was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/list_carrier_services_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
'/v1/connections/carriers/{carrier_name}':
summary: Carrier connections
description: Carrier connections
parameters:
- name: carrier_name
in: path
required: true
schema:
$ref: '#/components/schemas/carrier_name'
example: dhl_express
description: >-
The carrier name, such as `stamps_com`, `ups`, `fedex`, or
`dhl_express`.
post:
summary: Connect a carrier account
description: Connect a carrier account
tags:
- carrier_accounts
operationId: connect_carrier
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/connect_carrier_request_body'
responses:
'200':
description: The request was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/connect_carrier_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
'/v1/connections/carriers/{carrier_name}/{carrier_id}':
summary: Disconnect a carrier
description: Disconnect a carrier
parameters:
- name: carrier_name
in: path
required: true
schema:
$ref: '#/components/schemas/carrier_name'
example: dhl_express
description: >-
The carrier name, such as `stamps_com`, `ups`, `fedex`, or
`dhl_express`.
- name: carrier_id
in: path
required: true
schema:
$ref: '#/components/schemas/se_id'
example: se-28529731
description: Carrier ID
delete:
summary: Disconnect a carrier
description: Disconnect a carrier
tags:
- carrier_accounts
operationId: disconnect_carrier
responses:
'204':
description: The request was successful.
content:
text/plain:
schema:
$ref: '#/components/schemas/empty_response_body'
application/json:
schema:
$ref: '#/components/schemas/empty_response_body'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
'/v1/connections/carriers/{carrier_name}/{carrier_id}/settings':
summary: Carrier settings
description: Carrier settings
parameters:
- name: carrier_name
in: path
required: true
schema:
$ref: '#/components/schemas/carrier_name_with_settings'
example: dhl_express
description: 'The carrier name, such as `ups`, `fedex`, or `dhl_express`.'
- name: carrier_id
in: path
required: true
schema:
$ref: '#/components/schemas/se_id'
example: se-28529731
description: Carrier ID
get:
summary: Get carrier settings
description: Get carrier settings
tags:
- carrier_accounts
operationId: get_carrier_settings
responses:
'200':
description: The request was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/get_carrier_settings_response_body'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
put:
summary: Update carrier settings
description: Update carrier settings
tags:
- carrier_accounts
operationId: update_carrier_settings
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/update_carrier_settings_request_body'
responses:
'204':
description: The request was successful.
content:
text/plain:
schema:
$ref: '#/components/schemas/empty_response_body'
application/json:
schema:
$ref: '#/components/schemas/empty_response_body'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
/v1/connections/insurance/shipsurance:
summary: Shipsurance Connection
description: Shipsurance Connection
delete:
summary: Disconnect a Shipsurance Account
description: Disconnect a Shipsurance Account
operationId: disconnect_insurer
tags:
- insurance
responses:
'200':
description: The request was a success
content:
application/json:
schema:
$ref: '#/components/schemas/disconnect_insurer_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'500':
$ref: '#/components/responses/500_error_response'
post:
summary: Connect a Shipsurance Account
description: Connect a Shipsurance Account
operationId: connect_insurer
tags:
- insurance
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/connect_insurer_request_body'
required: true
responses:
'200':
description: The request was a success
content:
application/json:
schema:
$ref: '#/components/schemas/connect_insurer_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'500':
$ref: '#/components/responses/500_error_response'
'/v1/downloads/{dir}/{subdir}/{filename}':
summary: File Download
description: >
This endpoint is used to download forms that are generated in the various
pdf, png, zpl formats
such as labels and batches
parameters:
- name: subdir
in: path
required: true
schema:
type: string
- name: filename
in: path
required: true
schema:
type: string
- name: dir
in: path
required: true
schema:
type: string
get:
summary: Download File
description: Get File
operationId: download_file
tags:
- downloads
parameters:
- name: download
in: query
required: false
schema:
type: string
- name: rotation
in: query
required: false
schema:
type: integer
format: int32
responses:
'200':
description: The request was a success
content:
application/pdf:
schema:
$ref: '#/components/schemas/download_file_pdf_response_body'
image/png:
schema:
$ref: '#/components/schemas/download_file_png_response_body'
application/zpl:
schema:
$ref: '#/components/schemas/download_file_zpl_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
/v1/environment/webhooks:
summary: Webhooks
description: >
ShipEngine exposes asynchronous operations for long running operations
such as batch labels and rates.
Webhooks allow the ShipEngine servers to contact your servers when an
operation changes state, such as a batch label creation completion.
get:
summary: List Webhooks
description: List all webhooks currently enabled for the account.
tags:
- webhooks
operationId: list_webhooks
responses:
'200':
description: The request was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/list_webhooks_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'500':
$ref: '#/components/responses/500_error_response'
post:
summary: Create a Webhook
description: Create a webook for specific events in the environment.
tags:
- webhooks
operationId: create_webhook
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/create_webhook_request_body'
responses:
'200':
description: The request was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/create_webhook_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'409':
$ref: '#/components/responses/409_error_response'
'500':
$ref: '#/components/responses/500_error_response'
'/v1/environment/webhooks/{webhook_id}':
summary: Webhook
description: 'Retrieve, update, and delete information for individual webhooks'
parameters:
- name: webhook_id
in: path
required: true
schema:
$ref: '#/components/schemas/se_id'
description: Webhook ID
get:
summary: Get Webhook By ID
description: Retrieve individual webhook by an ID
tags:
- webhooks
operationId: get_webhook_by_id
responses:
'200':
description: The request was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/get_webhook_by_id_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
put:
summary: Update a Webhook
description: Update the webhook url property
tags:
- webhooks
operationId: update_webhook
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/update_webhook_request_body'
responses:
'204':
description: The request was successful.
content:
text/plain:
schema:
$ref: '#/components/schemas/empty_response_body'
application/json:
schema:
$ref: '#/components/schemas/empty_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
delete:
summary: Delete Webhook By ID
description: Delete a webhook
tags:
- webhooks
operationId: delete_webhook
responses:
'204':
description: The request was successful.
content:
text/plain:
schema:
$ref: '#/components/schemas/empty_response_body'
application/json:
schema:
$ref: '#/components/schemas/empty_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
/v1/insurance/shipsurance/add_funds:
summary: Shipsurance
description: >
[Shipsurance](https://www.shipsurance.com/) is a shipping insurance
company offering coverage for shipments sent via the major shipping
carriers worldwide.
patch:
summary: Add Funds To Insurance
description: >
You may need to auto fund your account from time to time. For example,
if you don't normally ship items over $100,
and may want to add funds to insurance rather than keeping the account
funded.
tags:
- insurance
operationId: add_funds_to_insurance
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/add_funds_to_insurance_request_body'
responses:
'200':
description: The request was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/add_funds_to_insurance_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'500':
$ref: '#/components/responses/500_error_response'
/v1/insurance/shipsurance/balance:
summary: Shipsurance
description: >
[Shipsurance](https://www.shipsurance.com/) is a shipping insurance
company offering coverage for shipments sent via the major shipping
carriers worldwide.
get:
summary: Get Insurance Funds Balance
description: Retrieve the balance of your Shipsurance account.
tags:
- insurance
operationId: get_insurance_balance
responses:
'200':
description: The request was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/get_insurance_balance_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'500':
$ref: '#/components/responses/500_error_response'
/v1/labels:
summary: Print shipping labels
description: >
Print shipping labels for any of the top global carriers in
minutes—instead of weeks. Simply [connect your existing carrier
accounts](https://www.shipengine.com/docs/carriers/setup/)
in the API dashboard, and then [begin creating
labels](https://www.shipengine.com/docs/shipping/use-a-carrier-service/).
get:
summary: List labels
description: >
This endpoint returns a list of labels that you've
[created](https://www.shipengine.com/docs/labels/create-a-label/). You
can optionally filter the results as well as control their sort order
and the number of results returned at a time.
By default, all labels are returned, 25 at a time, starting with the
most recently created ones. You can combine multiple filter options to
narrow-down the results. For example, if you only want to get your UPS
labels for your east coast warehouse you could query by both
`warehouse_id` and `carrier_id`
tags:
- labels
operationId: list_labels
parameters:
- name: label_status
in: query
required: false
schema:
$ref: '#/components/schemas/label_status'
description: Only return labels that are currently in the specified status
- name: service_code
in: query
required: false
schema:
$ref: '#/components/schemas/service_code'
example: usps_first_class_mail
description: >-
Only return labels for a specific [carrier
service](https://www.shipengine.com/docs/shipping/use-a-carrier-service/)
- description: >-
Only return labels for a specific [carrier
account](https://www.shipengine.com/docs/carriers/setup/)
name: carrier_id
in: query
required: false
schema:
$ref: '#/components/schemas/se_id'
- description: Only return labels with a specific tracking number
name: tracking_number
in: query
required: false
schema:
type: string
minLength: 1
example: '9405511899223197428490'
- description: >-
Only return labels that were created in a specific
[batch](https://www.shipengine.com/docs/labels/bulk/)
name: batch_id
in: query
required: false
schema:
$ref: '#/components/schemas/se_id'
- name: rate_id
in: query
required: false
schema:
$ref: '#/components/schemas/se_id'
description: Rate ID
- name: shipment_id
in: query
required: false
schema:
$ref: '#/components/schemas/se_id'
description: Shipment ID
- description: >-
Only return labels that originate from a specific
[warehouse](https://www.shipengine.com/docs/shipping/ship-from-a-warehouse/)
name: warehouse_id
in: query
required: false
schema:
$ref: '#/components/schemas/se_id'
- description: >-
Only return labels that were created on or after a specific
date/time
name: created_at_start
in: query
required: false
schema:
type: string
format: date-time
example: '2019-03-12T19:24:13.657Z'
- description: >-
Only return labels that were created on or before a specific
date/time
name: created_at_end
in: query
required: false
schema:
type: string
format: date-time
example: '2019-03-12T19:24:13.657Z'
- name: page
in: query
required: false
schema:
type: integer
format: int32
minimum: 1
default: 1
example: 2
description: >
Return a specific page of results. Defaults to the first page. If
set to a number that's greater than the number of pages of results,
an empty page is returned.
- name: page_size
in: query
required: false
schema:
type: integer
format: int32
minimum: 1
default: 25
example: 50
description: The number of results to return per response.
- name: sort_dir
in: query
required: false
schema:
allOf:
- $ref: '#/components/schemas/sort_dir'
default: desc
description: Controls the sort order of the query.
- name: sort_by
in: query
required: false
schema:
type: string
enum:
- modified_at
- created_at
default: created_at
description: Controls which field the query is sorted by.
responses:
'200':
description: >
The response includes a `labels` array containing a page of results
(as determined by the `page_size` query parameter). It also
includes other useful information, such as the total number of
labels that match the query criteria, the number of pages of
results, and the URLs of the first, last, next, and previous pages
of results.
content:
application/json:
schema:
$ref: '#/components/schemas/list_labels_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'500':
$ref: '#/components/responses/500_error_response'
post:
summary: Purchase Label
description: Purchase and print a label for shipment
tags:
- labels
operationId: create_label
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/create_label_request_body'
responses:
'200':
description: The requested object creation was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/create_label_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
'/v1/labels/external_shipment_id/{external_shipment_id}':
summary: Get Label By External Shipment ID
description: Find a label using the external shipment id
parameters:
- name: external_shipment_id
in: path
schema:
type: string
required: true
example: 0bcb569d-1727-4ff9-ab49-b2fec0cee5ae
get:
summary: Get Label By External Shipment ID
description: >
Find a label by using the external shipment id that was used during
label creation
tags:
- labels
operationId: get_label_by_external_shipment_id
parameters:
- name: label_download_type
in: query
required: false
schema:
$ref: '#/components/schemas/label_download_type'
example: url
responses:
'200':
description: The requested object creation was a success.
content:
application/json:
schema:
$ref: >-
#/components/schemas/get_label_by_external_shipment_id_response_body
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
'/v1/labels/rates/{rate_id}':
summary: Use a rate to purchase a label
description: >-
Purchase a label using a `rate_id` that has been previously generated
while looking at various rates for a particular shipment.
parameters:
- name: rate_id
in: path
required: true
schema:
$ref: '#/components/schemas/se_id'
description: Rate ID
post:
summary: Purchase Label with Rate ID
description: >
When retrieving rates for shipments using the `/rates` endpoint, the
returned information contains a `rate_id` property that can be used
to generate a label without having to refill in the shipment information
repeatedly.
tags:
- labels
operationId: create_label_from_rate
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/create_label_from_rate_request_body'
responses:
'200':
description: The requested object creation was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/create_label_from_rate_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
'/v1/labels/shipment/{shipment_id}':
summary: Purchase label using shipment ID
description: >
Purchase a label using a shipment ID that has already been created with
the desired address and
package info.
parameters:
- name: shipment_id
in: path
required: true
schema:
$ref: '#/components/schemas/se_id'
description: Shipment ID
post:
summary: Purchase Label with Shipment ID
description: >
Purchase a label using a shipment ID that has already been created with
the desired address and
package info.
tags:
- labels
operationId: create_label_from_shipment
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/create_label_from_shipment_request_body'
responses:
'200':
description: The requested object creation was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/create_label_from_shipment_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
'/v1/labels/{label_id}':
summary: Label
description: Retrieve information for individual labels.
parameters:
- name: label_id
in: path
required: true
schema:
$ref: '#/components/schemas/se_id'
description: Label ID
get:
summary: Get Label By ID
description: Retrieve information for individual labels.
tags:
- labels
operationId: get_label_by_id
parameters:
- name: label_download_type
in: query
required: false
schema:
$ref: '#/components/schemas/label_download_type'
example: url
responses:
'200':
description: The request was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/get_label_by_id_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
'/v1/labels/{label_id}/return':
summary: Return labels
parameters:
- name: label_id
in: path
required: true
schema:
$ref: '#/components/schemas/se_id'
description: Label ID
post:
summary: Create a return label
description: Create a return label
tags:
- labels
operationId: create_return_label
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/create_return_label_request_body'
responses:
'200':
description: The request was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/create_return_label_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
'/v1/labels/{label_id}/track':
summary: Tracking a Label
description: >-
Carriers will provide tracking information so the status of your shipment
can be monitored
parameters:
- name: label_id
in: path
required: true
schema:
$ref: '#/components/schemas/se_id'
description: Label ID
get:
summary: Get Label Tracking Information
description: Retrieve the label's tracking information
tags:
- labels
operationId: get_tracking_log_from_label
responses:
'200':
description: The request was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/get_tracking_log_from_label_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
'/v1/labels/{label_id}/void':
summary: Label Voiding
description: >
Some carriers charge for creating a label upon purchase vs upon use. The
Shipengine API allows you
to void a label to get a refund.
parameters:
- name: label_id
in: path
required: true
schema:
$ref: '#/components/schemas/se_id'
description: Label ID
put:
summary: Void a Label By ID
description: Void a label by ID to get a refund.
tags:
- labels
operationId: void_label
responses:
'200':
description: The request was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/void_label_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
/v1/manifests:
summary: Manifests
description: >
Many manifests are sent electronically to the carrier when you create a
label, and
often physical manifests are not necessary. Carriers receive the package
details, shipping date,
and other information that help them plan your package's delivery when you
create a label.
However, some providers, like USPS require manifests when shipping large
numbers of packages. Think about how long it would take for a delivery
driver to arrive, pick up 100 packages, and individually scan each of
them.
A manifest exists so the carrier can scan the manifest and check in all
the packages being shipped.
get:
summary: List Manifests
description: >-
Similar to querying shipments, we allow you to query manifests since
there will likely be a large number over a long period of time.
tags:
- manifests
operationId: list_manifests
parameters:
- name: warehouse_id
in: query
required: false
schema:
$ref: '#/components/schemas/se_id'
description: Warehouse ID
- name: ship_date_start
in: query
required: false
schema:
type: string
format: date-time
example: '2018-09-23T15:00:00.000Z'
description: ship date start range
- name: ship_date_end
in: query
required: false
schema:
type: string
format: date-time
example: '2018-09-23T15:00:00.000Z'
description: ship date end range
- name: created_at_start
in: query
required: false
schema:
type: string
format: date-time
example: '2019-03-12T19:24:13.657Z'
description: >-
Used to create a filter for when a resource was created (ex. A
shipment that was created after a certain time)
- name: created_at_end
in: query
required: false
schema:
type: string
format: date-time
example: '2019-03-12T19:24:13.657Z'
description: >-
Used to create a filter for when a resource was created, (ex. A
shipment that was created before a certain time)
- name: carrier_id
in: query
required: false
schema:
$ref: '#/components/schemas/se_id'
description: Carrier ID
- name: page
in: query
required: false
schema:
type: integer
format: int32
minimum: 1
default: 1
example: 2
description: >
Return a specific page of results. Defaults to the first page. If
set to a number that's greater than the number of pages of results,
an empty page is returned.
- name: page_size
in: query
required: false
schema:
type: integer
format: int32
minimum: 1
default: 25
example: 50
description: The number of results to return per response.
- name: label_ids
in: query
explode: true
required: false
schema:
type: array
items:
title: se_id
type: string
minLength: 1
maxLength: 25
pattern: '^se(-[a-z0-9]+)+$'
example: se-28529731
description: >-
A string that uniquely identifies a ShipEngine resource, such as
a carrier, label, shipment, etc.
description: Array of label ids
responses:
'200':
description: The request was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/list_manifests_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
post:
summary: Create Manifest
description: >
Each ShipEngine manifest is created for a specific warehouse, so you'll
need to provide the warehouse_id
rather than the ship_from address. You can create a warehouse for each
location that you want to create manifests for.
tags:
- manifests
operationId: create_manifest
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/create_manifest_request_body'
responses:
'200':
description: The request was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/create_manifest_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'500':
$ref: '#/components/responses/500_error_response'
'/v1/manifests/{manifest_id}':
summary: Manifest ID
description: Manifest ID
parameters:
- name: manifest_id
in: path
required: true
schema:
$ref: '#/components/schemas/se_id'
description: The Manifest Id
get:
summary: Get Manifest By Id
description: Get Manifest By Id
tags:
- manifests
operationId: get_manifest_by_id
responses:
'200':
description: The request was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/get_manifest_by_id_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
'/v1/manifests/requests/{manifest_request_id}':
summary: Manifest Request ID
description: Manifest Request ID
parameters:
- name: manifest_request_id
in: path
required: true
schema:
$ref: '#/components/schemas/se_id'
description: The Manifest Request Id
get:
summary: Get Manifest Request By Id
description: Get Manifest Request By Id
tags:
- manifests
operationId: get_manifest_request_by_id
responses:
'200':
description: The request was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/create_manifest_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
/v1/packages:
summary: Packages
description: >
Sometimes the default package types that carriers provide aren't enough
and you need to create your own. That's where
the `/packages` endpoint becomes useful. Create, manage, and delete custom
package types to suit your specific needs.
get:
summary: List Custom Package Types
description: List the custom package types associated with the account
tags:
- package_types
operationId: list_package_types
responses:
'200':
description: The request was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/list_package_types_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
post:
summary: Create Custom Package Type
description: >-
Create a custom package type to better assist in getting accurate rate
estimates
tags:
- package_types
operationId: create_package_type
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/create_package_type_request_body'
responses:
'200':
description: The request was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/create_package_type_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'500':
$ref: '#/components/responses/500_error_response'
'/v1/packages/{package_id}':
summary: Package
description: 'Create, edit, and delete individual custom packages.'
parameters:
- name: package_id
in: path
required: true
schema:
$ref: '#/components/schemas/se_id'
description: Package ID
get:
summary: Get Custom Package Type By ID
description: Get Custom Package Type by ID
tags:
- package_types
operationId: get_package_type_by_id
responses:
'200':
description: The request was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/get_package_type_by_id_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
put:
summary: Update Custom Package Type By ID
description: Update the custom package type object by ID
tags:
- package_types
operationId: update_package_type
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/update_package_type_request_body'
responses:
'204':
description: The request was successful.
content:
text/plain:
schema:
$ref: '#/components/schemas/empty_response_body'
application/json:
schema:
$ref: '#/components/schemas/empty_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
delete:
summary: Delete A Custom Package By ID
description: Delete a custom package using the ID
tags:
- package_types
operationId: delete_package_type
responses:
'204':
description: The request was successful.
content:
text/plain:
schema:
$ref: '#/components/schemas/empty_response_body'
application/json:
schema:
$ref: '#/components/schemas/empty_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
/v1/pickups:
summary: Scheduled Pickups
description: |
Scheduled package pickups
get:
summary: List Scheduled Pickups
description: List all pickups that have been scheduled for this carrier
tags:
- package_pickups
operationId: list_scheduled_pickups
parameters:
- name: carrier_id
in: query
required: false
schema:
$ref: '#/components/schemas/se_id'
description: Carrier ID
- name: warehouse_id
in: query
required: false
schema:
$ref: '#/components/schemas/se_id'
description: Warehouse ID
- description: >-
Only return scheduled pickups that were created on or after a
specific date/time
name: created_at_start
in: query
required: false
schema:
type: string
format: date-time
example: '2019-03-12T19:24:13.657Z'
- description: >-
Only return scheduled pickups that were created on or before a
specific date/time
name: created_at_end
in: query
required: false
schema:
type: string
format: date-time
example: '2019-03-12T19:24:13.657Z'
- name: page
in: query
required: false
schema:
type: integer
format: int32
minimum: 1
default: 1
example: 2
description: >
Return a specific page of results. Defaults to the first page. If
set to a number that's greater than the number of pages of results,
an empty page is returned.
- name: page_size
in: query
required: false
schema:
type: integer
format: int32
minimum: 1
default: 25
example: 50
description: The number of results to return per response.
responses:
'200':
description: The request was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/get_pickups_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
post:
summary: Schedule a Pickup
description: Schedule a package pickup with a carrier
tags:
- package_pickups
operationId: schedule_pickup
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/schedule_pickup_request_body'
responses:
'200':
description: The request was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/schedule_pickup_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
'/v1/pickups/{pickup_id}':
summary: Scheduled Pickup
description: |
A package pickup that has been scheduled with a carrier
parameters:
- name: pickup_id
in: path
required: true
schema:
$ref: '#/components/schemas/pickup_resource_id'
get:
summary: Get Pickup By ID
description: Get Pickup By ID
tags:
- package_pickups
operationId: get_pickup_by_id
responses:
'200':
description: The request was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/get_pickup_by_id_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
delete:
summary: Delete a Scheduled Pickup
description: Delete a previously-scheduled pickup by ID
tags:
- package_pickups
operationId: delete_scheduled_pickup
responses:
'200':
description: >
Return the `pickup_id` of the scheduled pickup that was successfully
deleted
content:
application/json:
schema:
$ref: '#/components/schemas/delete_pickup_by_id_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
/v1/rates:
summary: Rates
description: Get the various rates for a set of carriers
post:
summary: Get Shipping Rates
description: >
It's not uncommon that you want to give your customer the choice between
whether they want to ship the fastest, cheapest, or the most trusted
route. Most companies don't solely ship things using a single shipping
option;
so we provide functionality to show you all your options!
tags:
- rates
operationId: calculate_rates
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/calculate_rates_request_body'
responses:
'200':
description: The request was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/calculate_rates_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'500':
$ref: '#/components/responses/500_error_response'
/v1/rates/bulk:
summary: Bulk Rates
description: Get specific rates for large groups of shipments
post:
summary: Get Bulk Rates
description: Get Bulk Shipment Rates
tags:
- rates
operationId: compare_bulk_rates
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/compare_bulk_rates_request_body'
responses:
'200':
description: The request was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/compare_bulk_rates_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'500':
$ref: '#/components/responses/500_error_response'
/v1/rates/estimate:
summary: Rate Estimates
description: Show rate estimations between carriers with basic information.
post:
summary: Estimate Rates
description: Get Rate Estimates
tags:
- rates
operationId: estimate_rates
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/estimate_rates_request_body'
responses:
'200':
description: The request was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/estimate_rates_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'500':
$ref: '#/components/responses/500_error_response'
'/v1/rates/{rate_id}':
summary: Rate
description: Get Individual rate information.
parameters:
- name: rate_id
in: path
required: true
schema:
$ref: '#/components/schemas/se_id'
description: Rate ID
get:
summary: Get Rate By ID
description: Retrieve a previously queried rate by its ID
tags:
- rates
operationId: get_rate_by_id
responses:
'200':
description: The request was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/get_rate_by_id_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
/v1/service_points/list:
summary: Service Points
post:
summary: List Service Points
description: List carrier service points by location
operationId: service_points_list
tags:
- service_points
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/get_service_points_request'
responses:
'200':
description: The request was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/list_service_points_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
'/v1/service_points/{carrier_code}/{country_code}/{service_point_id}':
summary: Service Points
parameters:
- name: carrier_code
in: path
required: true
schema:
type: string
minLength: 1
example: stamps_com
description: Carrier code
- name: country_code
in: path
required: true
schema:
type: string
minLength: 2
maxLength: 2
example: CA
description: >
A two-letter [ISO 3166-1 country
code](https://en.wikipedia.org/wiki/ISO_3166-1)
- name: service_point_id
in: path
schema:
type: string
required: true
example: '614940'
get:
summary: Get Service Point By ID
description: Returns a carrier service point by using the service_point_id
operationId: service_points_get_by_id
tags:
- service_points
responses:
'200':
description: The request was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/get_service_point_by_id_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
/v1/shipments:
summary: Shipments
description: >
Shipments are the gatekeeper to more advanced functionality inside
ShipEngine. When you create a shipment, we respond with a shipment_id that
is a unique identifier inside of ShipEngine.
Additionally, we realize that you may have your own identifier, you can
set this by setting the `external_shipment_id` field in the request body.
get:
summary: List Shipments
description: Get list of Shipments
tags:
- shipments
operationId: list_shipments
parameters:
- name: shipment_status
in: query
required: false
schema:
$ref: '#/components/schemas/shipment_status'
- name: batch_id
in: query
required: false
schema:
$ref: '#/components/schemas/se_id'
description: Batch ID
- name: tag
in: query
required: false
schema:
type: string
minLength: 1
example: Letters_to_santa
description: >-
Search for shipments based on the custom tag added to the shipment
object
- name: created_at_start
in: query
required: false
schema:
type: string
format: date-time
example: '2019-03-12T19:24:13.657Z'
description: >-
Used to create a filter for when a resource was created (ex. A
shipment that was created after a certain time)
- name: created_at_end
in: query
required: false
schema:
type: string
format: date-time
example: '2019-03-12T19:24:13.657Z'
description: >-
Used to create a filter for when a resource was created, (ex. A
shipment that was created before a certain time)
- name: modified_at_start
in: query
required: false
schema:
type: string
format: date-time
example: '2019-03-12T19:24:13.657Z'
description: >-
Used to create a filter for when a resource was modified (ex. A
shipment that was modified after a certain time)
- name: modified_at_end
in: query
required: false
schema:
type: string
format: date-time
example: '2019-03-12T19:24:13.657Z'
description: >-
Used to create a filter for when a resource was modified (ex. A
shipment that was modified before a certain time)
- name: page
in: query
required: false
schema:
type: integer
format: int32
minimum: 1
default: 1
example: 2
description: >
Return a specific page of results. Defaults to the first page. If
set to a number that's greater than the number of pages of results,
an empty page is returned.
- name: page_size
in: query
required: false
schema:
type: integer
format: int32
minimum: 1
default: 25
example: 50
description: The number of results to return per response.
- name: sales_order_id
in: query
required: false
schema:
type: string
description: Sales Order ID
- name: sort_dir
in: query
required: false
schema:
allOf:
- $ref: '#/components/schemas/sort_dir'
default: desc
description: Controls the sort order of the query.
- name: sort_by
in: query
required: false
schema:
$ref: '#/components/schemas/shipments_sort_by'
example: modified_at
responses:
'200':
description: The request was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/list_shipments_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
post:
summary: Create Shipments
description: Create one or multiple shipments.
tags:
- shipments
operationId: create_shipments
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/create_shipments_request_body'
responses:
'200':
description: The requested object creation was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/create_shipments_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'500':
$ref: '#/components/responses/500_error_response'
'/v1/shipments/external_shipment_id/{external_shipment_id}':
summary: External Shipment ID
description: >
When a shipment object is created with a custom shipment ID, you can query
it using this endpoint
parameters:
- name: external_shipment_id
in: path
schema:
type: string
required: true
example: 0bcb569d-1727-4ff9-ab49-b2fec0cee5ae
get:
summary: Get Shipment By External ID
description: >-
Query Shipments created using your own custom ID convention using this
endpint
tags:
- shipments
operationId: get_shipment_by_external_id
responses:
'200':
description: The request was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/get_shipment_by_external_id_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
/v1/shipments/recognize:
summary: Parse shipping info
description: >
Data often enters your system as unstructured text (for example: emails,
SMS messages, support tickets, or other documents). ShipEngine's
shipment-recognition API helps you extract meaningful shipping data
(people's names, addresses, package weights and dimensions, insurance and
delivery requirements, etc.) from this unstructured text.
put:
summary: Parse shipping info
description: >
The shipment-recognition API makes it easy for you to extract shipping
data from unstructured text, including people's names, addresses,
package weights and dimensions, insurance and delivery requirements, and
more.
Data often enters your system as unstructured text (for example: emails,
SMS messages, support tickets, or other documents). ShipEngine's
shipment-recognition API helps you extract meaningful, structured data
from this unstructured text. The parsed shipment data is returned in the
same structure that's used for other ShipEngine APIs, so you can easily
use the parsed data to create a shipping label.
> **Note:** Shipment recognition is currently supported for the United
States, Canada, Australia, New Zealand, the United Kingdom, and Ireland.
tags:
- shipments
operationId: parse_shipment
requestBody:
required: true
description: >
The only required field is `text`, which is the text to be parsed. You
can optionally also provide a `shipment` containing any already-known
values. For example, you probably already know the `ship_from`
address, and you may also already know what carrier and service you
want to use.
content:
application/json:
schema:
$ref: '#/components/schemas/parse_shipment_request_body'
examples:
text_only:
summary: Text only
description: >
This is the simplest way to call the shipment-recognition API.
Just pass the text to be parsed and nothing else.
value:
text: >
I have a 4oz package that's 5x10x14in, and I need to ship it
to Margie McMiller at 3800 North Lamar suite 200 in austin,
tx 78652. Please send it via USPS first class and require an
adult signature. It also needs to be insured for $400.
some_known_fields:
summary: Some known fields
description: >
You can optionally provide a `shipment` object containing any
already-known values. For example, you probably already know
the `ship_from` address, and you may also already know what
carrier and service you want to use.
value:
text: >
I have a 4oz package that's 5x10x14in, and I need to ship it
to Margie McMiller at 3800 North Lamar suite 200 in austin,
tx 78652. Please send it via USPS first class and require an
adult signature. It also needs to be insured for $400.
shipment:
service_code: usps_first_class_mail
ship_from:
company_name: My Awesome Store
phone: 555-555-5555
address_line1: 587 Shotwell St.
address_line2: Suite 201
city_locality: San Francisco
state_province: CA
postal_code: 94110
country_code: US
address_residential_indicator: 'yes'
responses:
'200':
description: >
Returns the parsed shipment, as well as a confidence score and a
list of all the shipping entities that were recognized in the text.
content:
application/json:
schema:
$ref: '#/components/schemas/parse_shipment_response_body'
examples:
text_only:
description: >
This response shows that the shipment-recognition API was
able to recognize all the shipping entities in the text.
Notice that the `ship_from` field is not populated, since it
wasn't included in the request or in the parsed text.
value:
score: 0.9031369611169101
shipment:
carrier_id: se-118608
service_code: usps_first_class_mail
confirmation: adult_signature
ship_to:
name: Margie McMiller
company_name: Adult Signature
address_line1: 3800 North Lamar
address_line2: Suite 200
city_locality: Austin
state_province: TX
postal_code: 78652
address_residential_indicator: unknown
packages:
- weight:
value: 4
unit: ounce
dimensions:
length: 5
width: 10
height: 14
unit: inch
insured_value:
amount: 400
currency: USD
entities:
- type: weight
score: 0.9805313966503588
text: 4oz
start_index: 9
end_index: 11
result:
value: 4
unit: ounce
- type: dimensions
score: 1
text: 5x10x14in
start_index: 28
end_index: 36
result:
length: 5
width: 10
height: 14
unit: inch
- type: dimension
score: 0.9805313966503588
text: 14in
start_index: 33
end_index: 36
result:
unit: inch
value: 14
- type: address
score: 0.9281558837267101
text: >-
to Margie McMiller at 3800 North Lamar suite 200 in
austin, tx 78652. Please send it via USPS first class
and require an adult signature
start_index: 61
end_index: 196
result:
direction: to
name: Margie McMiller
company_name: Adult Signature
address_line1: 3800 North Lamar
address_line2: Suite 200
city_locality: Austin
state_province: TX
postal_code: 78652
- type: person
score: 0.9519646137063122
text: Margie McMiller
start_index: 64
end_index: 78
result:
value: Margie McMiller
- type: address_line
score: 0.9805313966503588
text: 3800 North Lamar
start_index: 83
end_index: 98
result:
line: 1
value: 3800 North Lamar
- type: number
score: 0.9805313966503588
text: 3800
start_index: 83
end_index: 86
result:
type: cardinal
value: 3800
- type: address_line
score: 1
text: suite 200
start_index: 100
end_index: 108
result:
line: 2
value: Suite 200
- type: dimension
score: 0.4792571878834418
text: 200 in
start_index: 106
end_index: 111
result:
unit: inch
value: 200
- type: city_locality
score: 0.9805313966503588
text: austin
start_index: 113
end_index: 118
result:
value: Austin
- type: state_province
score: 0.6082904353940255
text: tx
start_index: 121
end_index: 122
result:
name: Texas
value: TX
- type: postal_code
score: 0.9519646137063122
text: 78652
start_index: 124
end_index: 128
result:
value: 78652
- type: carrier
score: 0.9519646137063122
text: USPS
start_index: 150
end_index: 153
result:
name: Stamps.com
value: se-118608
- type: service
score: 0.6082904353940255
text: first class
start_index: 155
end_index: 165
result:
name: USPS First Class Mail
value: usps_first_class_mail
- type: number
score: 0.9805313966503588
text: first
start_index: 155
end_index: 159
result:
type: ordinal
value: 1
- type: company
score: 0.9519646137063122
text: adult signature
start_index: 182
end_index: 196
result:
value: Adult Signature
- type: delivery_confirmation
score: 0.8530163983409642
text: adult signature
start_index: 182
end_index: 196
result:
name: Adult Signature
value: adult_signature
- type: insurance
score: 0.8530163983409642
text: insured for $400
start_index: 219
end_index: 234
result:
value: 400
unit: USD
- type: insured_value
score: 1
text: $400
start_index: 231
end_index: 234
result:
unit: USD
value: 400
some_known_fields:
description: >
This response is shows that the shipment-recognition API was
able to recognize all the shipping entities in the text.
Notice that the `ship_from` and `service_code` fields are
populated with the values that were provided in the request.
value:
score: 0.9031369611169101
shipment:
carrier_id: se-118608
service_code: usps_first_class_mail
confirmation: adult_signature
ship_to:
name: Margie McMiller
company_name: Adult Signature
address_line1: 3800 North Lamar
address_line2: Suite 200
city_locality: Austin
state_province: TX
postal_code: 78652
address_residential_indicator: unknown
ship_from:
company_name: My Awesome Store
phone: 555-555-5555
address_line1: 587 Shotwell St.
address_line2: Suite 201
city_locality: San Francisco
state_province: CA
postal_code: 94110
country_code: US
address_residential_indicator: 'yes'
packages:
- weight:
value: 4
unit: ounce
dimensions:
length: 5
width: 10
height: 14
unit: inch
insured_value:
amount: 400
currency: USD
entities:
- type: weight
score: 0.9805313966503588
text: 4oz
start_index: 9
end_index: 11
result:
value: 4
unit: ounce
- type: dimensions
score: 1
text: 5x10x14in
start_index: 28
end_index: 36
result:
length: 5
width: 10
height: 14
unit: inch
- type: dimension
score: 0.9805313966503588
text: 14in
start_index: 33
end_index: 36
result:
unit: inch
value: 14
- type: address
score: 0.9281558837267101
text: >-
to Margie McMiller at 3800 North Lamar suite 200 in
austin, tx 78652. Please send it via USPS first class
and require an adult signature
start_index: 61
end_index: 196
result:
direction: to
name: Margie McMiller
company_name: Adult Signature
address_line1: 3800 North Lamar
address_line2: Suite 200
city_locality: Austin
state_province: TX
postal_code: 78652
- type: person
score: 0.9519646137063122
text: Margie McMiller
start_index: 64
end_index: 78
result:
value: Margie McMiller
- type: address_line
score: 0.9805313966503588
text: 3800 North Lamar
start_index: 83
end_index: 98
result:
line: 1
value: 3800 North Lamar
- type: number
score: 0.9805313966503588
text: 3800
start_index: 83
end_index: 86
result:
type: cardinal
value: 3800
- type: address_line
score: 1
text: suite 200
start_index: 100
end_index: 108
result:
line: 2
value: Suite 200
- type: dimension
score: 0.4792571878834418
text: 200 in
start_index: 106
end_index: 111
result:
unit: inch
value: 200
- type: city_locality
score: 0.9805313966503588
text: austin
start_index: 113
end_index: 118
result:
value: Austin
- type: state_province
score: 0.6082904353940255
text: tx
start_index: 121
end_index: 122
result:
name: Texas
value: TX
- type: postal_code
score: 0.9519646137063122
text: 78652
start_index: 124
end_index: 128
result:
value: 78652
- type: carrier
score: 0.9519646137063122
text: USPS
start_index: 150
end_index: 153
result:
name: Stamps.com
value: se-118608
- type: service
score: 0.6082904353940255
text: first class
start_index: 155
end_index: 165
result:
name: USPS First Class Mail
value: usps_first_class_mail
- type: number
score: 0.9805313966503588
text: first
start_index: 155
end_index: 159
result:
type: ordinal
value: 1
- type: company
score: 0.9519646137063122
text: adult signature
start_index: 182
end_index: 196
result:
value: Adult Signature
- type: delivery_confirmation
score: 0.8530163983409642
text: adult signature
start_index: 182
end_index: 196
result:
name: Adult Signature
value: adult_signature
- type: insurance
score: 0.8530163983409642
text: insured for $400
start_index: 219
end_index: 234
result:
value: 400
unit: USD
- type: insured_value
score: 1
text: $400
start_index: 231
end_index: 234
result:
unit: USD
value: 400
'400':
$ref: '#/components/responses/400_error_response'
'500':
$ref: '#/components/responses/500_error_response'
'/v1/shipments/{shipment_id}':
summary: Get and Update Shipment
description: Retrieve and Update and individual shipment based on its ID
parameters:
- name: shipment_id
in: path
required: true
schema:
$ref: '#/components/schemas/se_id'
description: Shipment ID
get:
summary: Get Shipment By ID
description: Get an individual shipment based on its ID
tags:
- shipments
operationId: get_shipment_by_id
responses:
'200':
description: The request was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/get_shipment_by_id_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
put:
summary: Update Shipment By ID
description: Update a shipment object based on its ID
tags:
- shipments
operationId: update_shipment
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/update_shipment_request_body'
responses:
'200':
description: The request was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/update_shipment_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
'/v1/shipments/{shipment_id}/cancel':
summary: Cancel Shipment
description: Cancel a Shipment
parameters:
- name: shipment_id
in: path
required: true
schema:
$ref: '#/components/schemas/se_id'
description: Shipment ID
put:
summary: Cancel a Shipment
description: >
Mark a shipment cancelled, if it is no longer needed or being used by
your organized. Any label associated with the shipment needs to be
voided first
An example use case would be if a batch label creation job is going to
run at a set time and only queries `pending` shipments. Marking a
shipment as cancelled
would remove it from this process
tags:
- shipments
operationId: cancel_shipments
responses:
'204':
description: The request was successful.
content:
text/plain:
schema:
$ref: '#/components/schemas/empty_response_body'
application/json:
schema:
$ref: '#/components/schemas/empty_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
'/v1/shipments/{shipment_id}/rates':
summary: Shipment Rates
description: >
Once a shipment is complete with the desired shipping information, you can
then search for rates available
based on the carriers associated with your account
parameters:
- name: shipment_id
in: path
required: true
schema:
$ref: '#/components/schemas/se_id'
description: Shipment ID
get:
summary: Get Shipment Rates
description: Get Rates for the shipment information associated with the shipment ID
tags:
- shipments
operationId: list_shipment_rates
parameters:
- name: created_at_start
in: query
required: false
schema:
type: string
format: date-time
example: '2019-03-12T19:24:13.657Z'
description: >-
Used to create a filter for when a resource was created (ex. A
shipment that was created after a certain time)
responses:
'200':
description: The request was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/list_shipment_rates_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
/v1/shipments/tags:
summary: Shipment Tags
description: >
Tags associated with the shipment object to be used to organize and query
shipment items.
put:
summary: Update Shipments Tags
description: Update Shipments Tags
tags:
- shipments
operationId: shipments_update_tags
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/update_shipments_tags_request_body'
required: true
responses:
'204':
description: NoContent
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
'/v1/shipments/{shipment_id}/tags':
summary: Shipment Tags
description: >
Tags associated with the shipment object to be used to organize and query
shipment items.
parameters:
- name: shipment_id
in: path
required: true
schema:
$ref: '#/components/schemas/se_id'
description: Shipment ID
get:
summary: Get Shipment Tags
description: Get Shipment tags based on its ID
tags:
- shipments
operationId: shipments_list_tags
responses:
'200':
description: The request was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/tag_shipment_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
'/v1/shipments/{shipment_id}/tags/{tag_name}':
summary: Shipment Tags
description: >
Tags associated with the shipment object to be used to organize and query
shipment items.
parameters:
- name: shipment_id
in: path
required: true
schema:
$ref: '#/components/schemas/se_id'
description: Shipment ID
- name: tag_name
in: path
required: true
schema:
$ref: '#/components/schemas/tag_name'
post:
summary: Add Tag to Shipment
description: Add a tag to the shipment object
tags:
- shipments
operationId: tag_shipment
responses:
'200':
description: The requested object creation was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/tag_shipment_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
delete:
summary: Remove Tag from Shipment
description: Remove an existing tag from the Shipment object
tags:
- shipments
operationId: untag_shipment
responses:
'204':
description: The request was successful.
content:
text/plain:
schema:
$ref: '#/components/schemas/empty_response_body'
application/json:
schema:
$ref: '#/components/schemas/empty_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
/v1/tags:
summary: Tags
description: >
Tags are simple text-based flags or identifiers. Tags can be used as a
simple label,
such as Guaranteed_Overnight or Fragile so shipments can be easily
[queried
later](https://www.shipengine.com/docs/reference/list-shipments/).
get:
summary: Get Tags
description: Get a list of all tags associated with an account.
tags:
- tags
operationId: list_tags
responses:
'200':
description: The request was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/list_tags_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
'/v1/tags/{tag_name}':
summary: Tag
description: Create and delete tags
parameters:
- name: tag_name
in: path
required: true
schema:
$ref: '#/components/schemas/tag_name'
post:
summary: Create a New Tag
description: Create a new Tag for customizing how you track your shipments
tags:
- tags
operationId: create_tag
responses:
'200':
description: The request was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/create_tag_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
delete:
summary: Delete Tag
description: Delete a tag that is no longer needed
tags:
- tags
operationId: delete_tag
responses:
'204':
description: The request was successful.
content:
text/plain:
schema:
$ref: '#/components/schemas/empty_response_body'
application/json:
schema:
$ref: '#/components/schemas/empty_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
'/v1/tags/{tag_name}/{new_tag_name}':
summary: Tag
description: Update tag name
parameters:
- name: tag_name
in: path
required: true
schema:
$ref: '#/components/schemas/tag_name'
- name: new_tag_name
in: path
required: true
schema:
$ref: '#/components/schemas/tag_name'
put:
summary: Update Tag Name
description: >-
Change a tag name while still keeping the relevant shipments attached to
it
tags:
- tags
operationId: rename_tag
responses:
'204':
description: The request was successful.
content:
text/plain:
schema:
$ref: '#/components/schemas/empty_response_body'
application/json:
schema:
$ref: '#/components/schemas/empty_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
/v1/tokens/ephemeral:
post:
summary: Get Ephemeral Token
description: >-
This endpoint returns a token that can be passed to an application for
authorized access. The lifetime of this token is 10 seconds.
operationId: tokens_get_ephemeral_token
parameters:
- name: redirect
in: query
required: false
schema:
$ref: '#/components/schemas/redirect'
description: >-
Include a redirect url to the application formatted with the
ephemeral token.
tags:
- tokens
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: >-
#/components/schemas/tokens_get_ephemeral_token_response_body.yaml
/v1/tracking:
summary: Tracking a Package
description: >-
If you generate your labels through ShipEngine, then you can subscribe to
real-time tracking events for free!
get:
summary: Get Tracking Information
description: Retrieve package tracking information
tags:
- tracking
operationId: get_tracking_log
parameters:
- name: carrier_code
in: query
required: false
schema:
type: string
minLength: 1
example: stamps_com
description: >
A [shipping
carrier](https://www.shipengine.com/docs/carriers/setup/), such as
`fedex`, `dhl_express`, `stamps_com`, etc.
- name: tracking_number
in: query
required: false
schema:
type: string
minLength: 1
example: '9405511899223197428490'
description: The tracking number associated with a shipment
responses:
'200':
description: The request was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/get_tracking_log_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
/v1/tracking/start:
summary: Start Tracking a Package
description: >
Allows you to subscribe to tracking updates for a package. You specify the
carrier_code and tracking_number of the package,
and receive notifications via webhooks whenever the shipping status
changes.
post:
summary: Start Tracking a Package
description: >
Allows you to subscribe to tracking updates for a package. You specify
the carrier_code and tracking_number of the package,
and receive notifications via webhooks whenever the shipping status
changes.
tags:
- tracking
operationId: start_tracking
parameters:
- name: carrier_code
in: query
required: false
schema:
type: string
minLength: 1
example: stamps_com
description: >
A [shipping
carrier](https://www.shipengine.com/docs/carriers/setup/), such as
`fedex`, `dhl_express`, `stamps_com`, etc.
- name: tracking_number
in: query
required: false
schema:
type: string
minLength: 1
example: '9405511899223197428490'
description: The tracking number associated with a shipment
responses:
'204':
description: The request was successful.
content:
text/plain:
schema:
$ref: '#/components/schemas/empty_response_body'
application/json:
schema:
$ref: '#/components/schemas/empty_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
/v1/tracking/stop:
summary: Stop Tracking a Package
description: Unsubscribe from tracking updates for a package.
post:
summary: Stop Tracking a Package
description: Unsubscribe from tracking updates for a package.
tags:
- tracking
operationId: stop_tracking
parameters:
- name: carrier_code
in: query
required: false
schema:
type: string
minLength: 1
example: stamps_com
description: >
A [shipping
carrier](https://www.shipengine.com/docs/carriers/setup/), such as
`fedex`, `dhl_express`, `stamps_com`, etc.
- name: tracking_number
in: query
required: false
schema:
type: string
minLength: 1
example: '9405511899223197428490'
description: The tracking number associated with a shipment
responses:
'204':
description: The request was successful.
content:
text/plain:
schema:
$ref: '#/components/schemas/empty_response_body'
application/json:
schema:
$ref: '#/components/schemas/empty_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
/v1/warehouses:
summary: Warehouses
description: >
You likely have one or more warehouse locations that you frequently ship
from, in which case it would be annoying to have to specify the
ship_from and return_to addresses on every shipment. The solution is to
[Create a
Warehouse](https://www.shipengine.com/docs/reference/create-warehouse/),
then you can simply pass the warehouse_id instead.
get:
summary: List Warehouses
description: Retrieve a list of warehouses associated with this account.
tags:
- warehouses
operationId: list_warehouses
responses:
'200':
description: The request was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/list_warehouses_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
post:
summary: Create Warehouse
description: >
Create a warehouse location that you can use to create shipping items by
simply passing in the generated warehouse id.
If the return address is not supplied in the request body then it is
assumed that the origin address is the return address as well
tags:
- warehouses
operationId: create_warehouse
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/create_warehouse_request_body'
responses:
'200':
description: The request was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/create_warehouse_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
'/v1/warehouses/{warehouse_id}':
summary: Warehouse
description: >
You likely have one or more warehouse locations that you frequently ship
from, in which case it would be annoying to have to specify the
ship_from and return_to addresses on every shipment. The solution is to
[Create a
Warehouse](https://www.shipengine.com/docs/reference/create-warehouse/),
then you can simply pass the warehouse_id instead.
parameters:
- name: warehouse_id
in: path
required: true
schema:
$ref: '#/components/schemas/se_id'
description: Warehouse ID
get:
summary: Get Warehouse By Id
description: Retrieve warehouse data based on the warehouse ID
tags:
- warehouses
operationId: get_warehouse_by_id
responses:
'200':
description: The request was a success.
content:
application/json:
schema:
$ref: '#/components/schemas/get_warehouse_by_id_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
put:
summary: Update Warehouse By Id
description: Update Warehouse object information
tags:
- warehouses
operationId: update_warehouse
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/update_warehouse_request_body'
responses:
'204':
description: The request was successful.
content:
text/plain:
schema:
$ref: '#/components/schemas/empty_response_body'
application/json:
schema:
$ref: '#/components/schemas/empty_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
delete:
summary: Delete Warehouse By ID
description: Delete a warehouse by ID
tags:
- warehouses
operationId: delete_warehouse
responses:
'204':
description: The request was successful.
content:
text/plain:
schema:
$ref: '#/components/schemas/empty_response_body'
application/json:
schema:
$ref: '#/components/schemas/empty_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
'/v1/warehouses/{warehouse_id}/settings':
summary: Warehouse settings
description: Warehouse settings
parameters:
- name: warehouse_id
in: path
required: true
schema:
$ref: '#/components/schemas/se_id'
description: Warehouse ID
put:
summary: Update Warehouse Settings
description: Update Warehouse settings object information
tags:
- warehouses
operationId: update_warehouse_settings
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/update_warehouse_settings_request_body'
responses:
'204':
description: The request was successful.
content:
text/plain:
schema:
$ref: '#/components/schemas/empty_response_body'
application/json:
schema:
$ref: '#/components/schemas/empty_response_body'
'400':
$ref: '#/components/responses/400_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
servers:
- url: 'https://api.shipengine.com'
components:
schemas:
get_account_settings_response_body:
title: get_account_settings_response_body
allOf:
- $ref: '#/components/schemas/list_account_settings_body'
list_account_settings_body:
title: list_account_settings_body
type: object
description: An account settings list response body
additionalProperties: false
allOf:
- $ref: '#/components/schemas/account_settings'
account_settings:
title: account_settings
type: object
description: A ShipEngine account settings response body
additionalProperties: false
properties:
default_label_layout:
allOf:
- $ref: '#/components/schemas/default_label_layout'
default_label_layout:
title: default_label_layout
type: string
enum:
- 4x6
- Letter
description: The possible default label layout values
error_response_body:
title: error_response_body
type: object
description: An error response body
required:
- request_id
- errors
additionalProperties: false
properties:
request_id:
allOf:
- $ref: '#/components/schemas/uuid'
description: >
A UUID that uniquely identifies the request id.
This can be given to the support team to help debug non-trivial
issues that may occur
errors:
type: array
readOnly: true
items:
allOf:
- $ref: '#/components/schemas/error'
description: The errors associated with the failed API call
uuid:
title: uuid
type: string
format: uuid
minLength: 36
maxLength: 36
pattern: >-
^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
example: aa3d8e8e-462b-4476-9618-72db7f7b7009
description: A UUID (a.k.a. GUID) that uniquely identifies a resource
error:
title: error
type: object
description: |
The error structure that gets returned with almost all failed API calls
required:
- error_source
- error_type
- error_code
- message
additionalProperties: false
properties:
error_source:
allOf:
- $ref: '#/components/schemas/error_source'
error_type:
allOf:
- $ref: '#/components/schemas/error_type'
error_code:
allOf:
- $ref: '#/components/schemas/error_code'
message:
type: string
readOnly: true
example: Body of request cannot be null.
minLength: 1
description: An error message associated with the failed API call
error_source:
title: error_source
type: string
enum:
- carrier
- order_source
- shipengine
description: >
The source of the error, as indicated by the name this informs us if the
API call failed because of the
carrier, the order source, or the ShipEngine API itself.
error_type:
title: error_type
type: string
enum:
- account_status
- business_rules
- validation
- security
- system
- integrations
description: |
The type of error
error_code:
title: error_code
type: string
enum:
- auto_fund_not_supported
- batch_cannot_be_modified
- carrier_conflict
- carrier_disconnected
- carrier_not_connected
- carrier_not_supported
- confirmation_not_supported
- default_warehouse_cannot_be_deleted
- field_conflict
- field_value_required
- forbidden
- identifier_conflict
- identifiers_must_match
- insufficient_funds
- invalid_address
- invalid_billing_plan
- invalid_field_value
- invalid_identifier
- invalid_status
- invalid_string_length
- label_images_not_supported
- meter_failure
- order_source_not_active
- rate_limit_exceeded
- refresh_not_supported
- request_body_required
- return_label_not_supported
- settings_not_supported
- subscription_inactive
- terms_not_accepted
- tracking_not_supported
- trial_expired
- unauthorized
- unknown
- unspecified
- verification_failure
- warehouse_conflict
- webhook_event_type_conflict
- customs_items_required
- incompatible_paired_labels
- invalid_charge_event
- invalid_object
- no_rates_returned
description: The error code specified for the failed API Call
list_account_settings_images_response_body:
title: list_account_settings_images_response_body
allOf:
- $ref: '#/components/schemas/list_account_images_response_body'
list_account_images_response_body:
title: list_account_images_response_body
type: object
description: A list account images response body
required:
- images
additionalProperties: false
properties:
images:
type: array
readOnly: true
minItems: 0
items:
allOf:
- title: account_settings_images
type: object
description: A ShipEngine account images body
additionalProperties: false
properties:
label_image_id:
readOnly: true
allOf:
- $ref: '#/components/schemas/image_id'
description: >
A string that uniquely identifies the image. This ID is
generated by ShipEngine when the image is uploaded.
name:
type: string
minLength: 1
maxLength: 50
example: My logo
description: |
A human readable name for the image.
is_default:
type: boolean
example: false
description: |
Indicates whether this image is set as default.
image_content_type:
allOf:
- type: string
enum:
- image/png
- image/jpeg
description: The image type
description: |
The file type of the image.
image_data:
type: string
example: >-
iVBORw0KGgoAAAANSUhEUgAAABkAAAAZCAYAAADE6YVjAAAAAXNSR0IArs4c6QAAAiVJREFUSEu91j3IeVEcB/CvSTIoBrFSikEZMdjsjExeUspgUEp5SUpeshrIgEFJJmWwMZHJQGHDhJSXTPfpnH/8ebzd56HnN93u7ZzP/f1+55x7Ob1ejxEKheByufh0HI9HrFYrcKbTKUMu5HI5BALBx5zNZoPxeAySAGc2mzF8Pp/e+BR0Ash8u93uHyKVSnH54J2Mvs8zn8//I6RO70L3xt8g70CPXvAu8hvoWQUeIj+BXpX4KcIGegWQOV4izyA2AGvkHsQW+BFyCUkkEiwWC9Ybl1W5Ls8ZMoAABCIbmE3cINFoFMFgEEajEeVyGSKRCJ1OB3q9ns5nMpmQTCaxXq9/l8loNEKj0YDX66UACYvFQq9brRYcDgdUKhU9RD/SEwLm83lEIhGUSiX0+33E4/GrU5otRMs1mUyYbDYLu90OhUJBMzhlZbPZ4Pf7odFo4HQ6b1rABqJIvV5nttstLc0pSIn2+z0tTy6XQ6FQoI/a7TZ0Ot0V9gqiiMFgYKrVKm0yieVyCZ/PB6vVSpF0Ok2zJHEqIY/HYw1RxOfzMYlE4jwoEAhAJpPBbDZf9eBwOCCVSsHtdp9f6FJ6egorlUqmVqvRfjSbTXS7XXg8nptP8Svk0RF01ROtVguSUTgchlgsPpeOZBaLxTAcDlEsFpHJZPC9XM8yoshgMGBCoRBdQWTCU7hcLjohWb5kM6rValQqlfMKfLbbb77xf/K38hf/XV9ilOpnLqvnogAAAABJRU5ErkJggg==
description: |
A base64 encoded string representation of the image.
created_at:
readOnly: true
allOf:
- $ref: '#/components/schemas/date_time'
description: >-
The date and time that the image was created in
ShipEngine.
modified_at:
readOnly: true
allOf:
- $ref: '#/components/schemas/date_time'
description: >-
The date and time that the image was modified in
ShipEngine.
description: Image
description: Image List
allOf:
- $ref: '#/components/schemas/paged_list_response_body'
paged_list_response_body:
title: paged_list_response_body
type: object
required:
- total
- page
- pages
- links
additionalProperties: true
properties:
total:
type: integer
minimum: 0
example: 2750
description: The total number of items across all pages of results
page:
type: integer
minimum: 1
example: 1
description: >-
The current page number of results. For example, if there are 80
results, and the page size is 25, then `page` could be 1, 2, 3, or
4. The first three pages would contain 25 items each, and the
fourth page would contain the five remaining items.
pages:
type: integer
minimum: 0
example: 4
description: >-
The total number of pages of results. For example, if there are 80
results, and the page size is 25, then `pages` would be 4. The
first three pages would contain 25 items each, and the fourth page
would contain the five remaining items. If there are no results,
then `pages` will be zero.
links:
allOf:
- $ref: '#/components/schemas/pagination_link'
description: >
Many ShipEngine endpoints return a paged list of items. In addition to
the returned items, these responses also include information about the
total number of items, the number of pages of results, and URLs of other
pages of results.
pagination_link:
title: pagination_link
type: object
description: Helpful links to other pages of results
required:
- first
- last
- prev
- next
additionalProperties: false
properties:
first:
allOf:
- $ref: '#/components/schemas/link'
description: >
The link to the first page of results. This object will _always_
have an `href` field. If there are no results, then the first page
will contain an empty array of items.
last:
allOf:
- $ref: '#/components/schemas/link'
description: >
The link to the final page of results. This object will _always_
have an `href` field. If there are no results, then the final page
will contain an empty array of items.
prev:
allOf:
- $ref: '#/components/schemas/optional_link'
description: >
The link to the previous page of results. The `href` field will
only be set when the `page` is 2 or greater.
next:
allOf:
- $ref: '#/components/schemas/optional_link'
description: >
The link to the next page of results. The `href` field will only be
set when the `page` is less than `pages`.
link:
title: link
type: object
description: A link to a related resource
additionalProperties: false
required:
- href
allOf:
- $ref: '#/components/schemas/optional_link'
optional_link:
title: optional_link
type: object
description: >-
A link to a related resource, or an empty object if there is no resource
to link to
additionalProperties: false
properties:
href:
allOf:
- $ref: '#/components/schemas/url'
description: 'The URL of the linked resource, if any'
type:
type: string
minLength: 1
description: >-
The type of resource, or the type of relationship to the parent
resource
url:
title: url
type: string
format: url
minLength: 1
example: 'http://api.shipengine.com/v1/labels/se-28529731'
description: A URL
create_account_settings_image_request_body:
title: create_account_settings_image_request_body
type: object
description: A ShipEngine account settings images request body
required:
- name
- image_content_type
- image_data
additionalProperties: false
allOf:
- $ref: '#/components/schemas/account_settings_images'
account_settings_images:
title: account_settings_images
type: object
description: A ShipEngine account images body
additionalProperties: false
properties:
label_image_id:
readOnly: true
allOf:
- $ref: '#/components/schemas/image_id'
description: >
A string that uniquely identifies the image. This ID is generated by
ShipEngine when the image is uploaded.
name:
type: string
minLength: 1
maxLength: 50
example: My logo
description: |
A human readable name for the image.
is_default:
type: boolean
example: false
description: |
Indicates whether this image is set as default.
image_content_type:
allOf:
- type: string
enum:
- image/png
- image/jpeg
description: The image type
description: |
The file type of the image.
image_data:
type: string
example: >-
iVBORw0KGgoAAAANSUhEUgAAABkAAAAZCAYAAADE6YVjAAAAAXNSR0IArs4c6QAAAiVJREFUSEu91j3IeVEcB/CvSTIoBrFSikEZMdjsjExeUspgUEp5SUpeshrIgEFJJmWwMZHJQGHDhJSXTPfpnH/8ebzd56HnN93u7ZzP/f1+55x7Ob1ejxEKheByufh0HI9HrFYrcKbTKUMu5HI5BALBx5zNZoPxeAySAGc2mzF8Pp/e+BR0Ash8u93uHyKVSnH54J2Mvs8zn8//I6RO70L3xt8g70CPXvAu8hvoWQUeIj+BXpX4KcIGegWQOV4izyA2AGvkHsQW+BFyCUkkEiwWC9Ybl1W5Ls8ZMoAABCIbmE3cINFoFMFgEEajEeVyGSKRCJ1OB3q9ns5nMpmQTCaxXq9/l8loNEKj0YDX66UACYvFQq9brRYcDgdUKhU9RD/SEwLm83lEIhGUSiX0+33E4/GrU5otRMs1mUyYbDYLu90OhUJBMzhlZbPZ4Pf7odFo4HQ6b1rABqJIvV5nttstLc0pSIn2+z0tTy6XQ6FQoI/a7TZ0Ot0V9gqiiMFgYKrVKm0yieVyCZ/PB6vVSpF0Ok2zJHEqIY/HYw1RxOfzMYlE4jwoEAhAJpPBbDZf9eBwOCCVSsHtdp9f6FJ6egorlUqmVqvRfjSbTXS7XXg8nptP8Svk0RF01ROtVguSUTgchlgsPpeOZBaLxTAcDlEsFpHJZPC9XM8yoshgMGBCoRBdQWTCU7hcLjohWb5kM6rValQqlfMKfLbbb77xf/K38hf/XV9ilOpnLqvnogAAAABJRU5ErkJggg==
description: |
A base64 encoded string representation of the image.
created_at:
readOnly: true
allOf:
- $ref: '#/components/schemas/date_time'
description: The date and time that the image was created in ShipEngine.
modified_at:
readOnly: true
allOf:
- $ref: '#/components/schemas/date_time'
description: The date and time that the image was modified in ShipEngine.
image_id:
title: image_id
type: string
minLength: 4
example: img_DtBXupDBxREpHnwEXhTfgK
description: Used to identify an image resource.
date_time:
title: date_time
type: string
format: date-time
pattern: '^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[-+]\d{2}:\d{2})$'
example: '2018-09-23T15:00:00.000Z'
description: >
An [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) string that
represents a date and time.
get_account_settings_images_response_body:
title: get_account_settings_images_response_body
type: object
description: A get account images by id response body
additionalProperties: false
allOf:
- $ref: '#/components/schemas/account_settings_images'
empty_response_body:
title: empty_response_body
type: string
minLength: 0
maxLength: 0
update_account_settings_image_request_body:
title: update_account_settings_image_request_body
type: object
description: A ShipEngine account settings images request body
required:
- is_default
additionalProperties: false
allOf:
- $ref: '#/components/schemas/account_settings_images'
parse_address_request_body:
title: parse_address_request_body
type: object
description: >
The only required field is `text`, which is the text to be parsed. You
can optionally also provide an `address` containing already-known
values. For example, you may already know the recipient's name, city,
and country, and only want to parse the street address into separate
lines.
required:
- text
additionalProperties: false
properties:
text:
type: string
minLength: 1
example: >-
Margie McMiller at 3800 North Lamar suite 200 in austin, tx. The
zip code there is 78652.
description: The unstructured text that contains address-related entities
address:
allOf:
- $ref: '#/components/schemas/partial_address'
description: >
You can optionally provide any already-known address values. For
example, you may already know the recipient's name, city, and
country, and only want to parse the street address into separate
lines.
partial_address:
title: partial_address
type: object
description: A complete or partial mailing address.
additionalProperties: false
properties:
name:
type: string
minLength: 1
example: John Doe
description: >
The name of a contact person at this address. This field may be set
instead of - or in addition to - the `company_name` field.
phone:
type: string
minLength: 1
example: +1 204-253-9411 ext. 123
description: >
The phone number of a contact person at this address. The format of
this phone number varies depending on the country.
email:
type: string
nullable: true
example: example@example.com
description: |
Email for the address owner.
company_name:
type: string
minLength: 1
nullable: true
example: The Home Depot
description: >
If this is a business address, then the company name should be
specified here.
address_line1:
type: string
minLength: 1
example: 1999 Bishop Grandin Blvd.
description: >
The first line of the street address. For some addresses, this may
be the only line. Other addresses may require 2 or 3 lines.
address_line2:
type: string
minLength: 1
nullable: true
example: Unit 408
description: >
The second line of the street address. For some addresses, this
line may not be needed.
address_line3:
type: string
minLength: 1
nullable: true
example: 'Building #7'
description: >
The third line of the street address. For some addresses, this line
may not be needed.
city_locality:
type: string
minLength: 1
example: Winnipeg
description: The name of the city or locality
state_province:
type: string
minLength: 1
example: Manitoba
description: >
The state or province. For some countries (including the U.S.) only
abbreviations are allowed. Other countries allow the full name or
abbreviation.
postal_code:
allOf:
- $ref: '#/components/schemas/postal_code'
country_code:
allOf:
- $ref: '#/components/schemas/country_code'
description: >
The two-letter [ISO 3166-1 country
code](https://en.wikipedia.org/wiki/ISO_3166-1)
address_residential_indicator:
default: unknown
example: 'no'
description: Indicates whether this is a residential address.
allOf:
- $ref: '#/components/schemas/address_residential_indicator'
postal_code:
title: postal_code
minLength: 1
type: string
example: 78756-3717
description: postal code
country_code:
title: country_code
type: string
minLength: 2
maxLength: 2
example: CA
description: >
A two-letter [ISO 3166-1 country
code](https://en.wikipedia.org/wiki/ISO_3166-1)
address_residential_indicator:
title: address_residential_indicator
type: string
enum:
- unknown
- 'yes'
- 'no'
description: Indicates whether an address is residential.
parse_address_response_body:
title: parse_address_response_body
type: object
description: >
The parsed address, as well as a confidence score and a list of all the
entities that were recognized in the text.
required:
- score
- address
- entities
additionalProperties: false
properties:
score:
type: number
format: double
minimum: 0
maximum: 1
description: >
A confidence score between zero and one that indicates how certain
the API is that it understood the text.
address:
allOf:
- $ref: '#/components/schemas/partial_address'
description: >
The parsed address. This address may not be complete, depending on
how much information was included in the text and how confident the
API is about each recognized entity.
> **Note:** The address-recognition API does not currently perform
any validation of the parsed address, so we recommend that you use
the [address-validation
API](https://www.shipengine.com/docs/addresses/validation/) to
ensure that the address is correct.
entities:
type: array
minItems: 0
items:
$ref: '#/components/schemas/recognized_entity'
description: >
All of the entities that were recognized in the text. An "entity" is
a single piece of data, such as a city, a postal code, or an address
line. Each entity includes the original text and the parsed value.
recognized_entity:
title: recognized_entity
type: object
description: >
An entity is a single piece of data that was recognized in unstructured
text. For example, a city, a postal code, package dimensions, insured
value, etc. Each entity includes the original text and the parsed
value.
required:
- type
- score
- text
- start_index
- end_index
additionalProperties: false
properties:
type:
type: string
minLength: 1
description: 'The Entity type (e.g. "weight", "person", "address_line1", etc.)'
score:
format: double
minimum: 0
maximum: 1
type: number
description: >
A confidence score between zero and one that indicates how certain
the API is that it correctly recognized this entity
text:
type: string
minLength: 1
description: >-
The substring from the original text that was recognized as this
entity
start_index:
type: integer
minimum: 0
description: >-
The index of the first character of this entity within the original
text
end_index:
type: integer
minimum: 0
description: >-
The index of the last character of this entity within the original
text
result:
$ref: '#/components/schemas/normalized_entity'
normalized_entity:
title: normalized_entity
type: object
additionalProperties: true
properties: {}
description: >
The normalized value of the entity.
Most entity results have a `value` field, which is the normalized value
of the entity. For example, if the substring "john doe" was recognized
as a "person" entity, then the value might be normalized to have proper
capitalization (e.g. "John Doe"). Or if the substring "ft worth" was
recognized as a "city" entity, then the value might be normalized to
"Fort Worth".
Some entities have other information in addition to, or instead of a
`value`. For example, a "dimensions" entity will have separate fields
for `length`, `width`, `height`, and `unit`.
validate_address_request_body:
title: validate_address_request_body
type: array
description: An address validation request body
items:
allOf:
- $ref: '#/components/schemas/address_to_validate'
description: An array of addresses to validate.
address_to_validate:
title: address_to_validate
type: object
description: |
Any residential or business mailing address, anywhere in the world.
required:
- address_line1
- city_locality
- state_province
- country_code
additionalProperties: false
allOf:
- $ref: '#/components/schemas/partial_address'
validate_address_response_body:
title: validate_address_response_body
type: array
description: An address validation response body
items:
readOnly: true
allOf:
- $ref: '#/components/schemas/address_validation_result'
description: The address validation response body
address_validation_result:
title: address_validation_result
type: object
description: An address validation result
required:
- status
- original_address
- matched_address
- messages
additionalProperties: false
properties:
status:
allOf:
- $ref: '#/components/schemas/address_validation_status'
original_address:
allOf:
- $ref: '#/components/schemas/address'
description: The original address that was sent for validation
matched_address:
nullable: true
readOnly: true
allOf:
- $ref: '#/components/schemas/address'
description: The matched address found by the Shipengine API
messages:
type: array
readOnly: true
default: []
items:
$ref: '#/components/schemas/response_message'
description: >-
The list of messages that were generated during the address
validation request.
address_validation_status:
title: address_validation_status
type: string
enum:
- unverified
- verified
- warning
- error
description: The possible address validation status values
address:
title: address
type: object
description: >
Any residential or business mailing address, anywhere in the world.
> **Note:** Either `name` or `company_name` must be set. Both may be
specified, if relevant.
required:
- name
- phone
- address_line1
- city_locality
- state_province
- postal_code
- country_code
- address_residential_indicator
additionalProperties: false
allOf:
- $ref: '#/components/schemas/partial_address'
response_message:
title: response_message
type: object
description: >-
A response message that displays when additional info is needed for an
address validation request.
additionalProperties: false
required:
- code
- message
- type
- detail_code
properties:
code:
readOnly: true
allOf:
- $ref: '#/components/schemas/address_validation_code'
message:
type: string
readOnly: true
example: Invalid Postal Code
minLength: 1
description: Message explaining the address validation error
type:
readOnly: true
allOf:
- $ref: '#/components/schemas/address_validation_message_type'
detail_code:
nullable: true
allOf:
- $ref: '#/components/schemas/address_validation_detail_code'
address_validation_code:
title: address_validation_code
type: string
enum:
- a1000
- a1001
- a1002
- a1003
- a1004
- a1005
- a1006
- a1007
- a1008
- r1000
- r1001
- r1002
- r1003
description: The error codes that can be returned by the address validation API
address_validation_message_type:
title: address_validation_message_type
type: string
enum:
- error
- warning
- info
description: >-
The different types of messages that can be returned by the address
validation API
address_validation_detail_code:
title: address_validation_detail_code
type: string
enum:
- unsupported_country
- non_supported_country
- minimum_postal_code_verification_failed
- street_does_not_match_unique_street_name
- multiple_directionals
- multiple_matches
- suite_not_valid
- suite_missing
- incompatible_paired_labels
- invalid_house_number
- missing_house_number
- invalid_box_number
- invalid_charge_event
- missing_box_number
- missing_cmra_or_private_mail_box_number
- suite_has_no_secondaries
- postal_code_changed_or_added
- state_province_changed_or_added
- city_locality_changed_or_added
- urbanization_changed
- street_name_spelling_changed_or_added
- street_name_type_changed_or_added
- street_direction_changed_or_added
- suite_type_changed_or_added
- suite_unit_number_changed_or_added
- double_dependent_locality_changed_or_added
- subadministrative_area_changed_or_added
- subnational_area_changed_or_added
- po_box_changed_or_added
- premise_type_changed_or_added
- house_number_changed
- organization_changed_or_added
- partially_verified_to_state_level
- partially_verified_to_city_level
- partially_verified_to_street_level
- partially_verified_to_premise_level
- verified_to_state_level
- verified_to_city_level
- verified_to_street_level
- verified_to_premise_level
- verified_to_suite_level
- coded_to_street_lavel
- coded_to_neighborhood_level
- coded_to_community_level
- coded_to_state_level
- coded_to_rooftop_level
- coded_to_rooftop_interpolation_level
- name_max_length_exceeded
- phone_max_length_exceeded
- company_name_max_length_exceeded
- line1_min_max_length
- line2_max_length_exceeded
- line3_max_length_exceeded
- city_locality_max_length_exceeded
- state_province_max_length_exceeded
- invalid_postal_code
- country_invalid_length
- address_not_found
description: >-
The detailed error codes that can be returned by the address validation
API
batch_status:
title: batch_status
type: string
enum:
- open
- queued
- processing
- completed
- completed_with_errors
- archived
- notifying
- invalid
description: The possible batch status values
sort_dir:
title: sort_dir
type: string
enum:
- asc
- desc
description: |
Controls the sort order of queries
|Value |Description
|:---------|:-----------------------------------------------------
|`asc` |Return results in ascending order
|`desc` |Return results in descending order
batches_sort_by:
title: batches_sort_by
type: string
enum:
- ship_date
- processed_at
- created_at
description: The possible batches sort by values
list_batches_response_body:
title: list_batches_response_body
type: object
description: A list batch response body
required:
- batches
- total
- page
- pages
- links
additionalProperties: false
properties:
batches:
type: array
readOnly: true
minItems: 0
items:
allOf:
- $ref: '#/components/schemas/batch'
description: Batch
description: Batch List
total:
type: integer
format: int64
readOnly: true
minimum: 0
example: 10
description: The total number of batches the API call returned
page:
type: integer
format: int32
readOnly: true
minimum: 1
example: 1
description: The page that is currently being read
pages:
type: integer
format: int32
readOnly: true
minimum: 1
example: 10
description: The total number of batch pages the API call returned
links:
readOnly: true
allOf:
- $ref: '#/components/schemas/pagination_link'
batch:
title: batch
type: object
description: >
Batches are an advanced feature of ShipEngine designed for users who
need to generate hundreds or
thousands of labels at a time.
required:
- label_layout
- label_format
- batch_id
- batch_number
- external_batch_id
- batch_notes
- created_at
- processed_at
- errors
- process_errors
- warnings
- completed
- forms
- count
- batch_shipments_url
- batch_labels_url
- batch_errors_url
- label_download
- form_download
- paperless_download
- status
additionalProperties: false
properties:
label_layout:
readOnly: true
default: 4x6
description: label layout
allOf:
- $ref: '#/components/schemas/label_layout'
label_format:
readOnly: true
default: pdf
allOf:
- $ref: '#/components/schemas/label_format'
batch_id:
readOnly: true
allOf:
- $ref: '#/components/schemas/se_id'
description: A string that uniquely identifies the batch
batch_number:
readOnly: true
type: string
minLength: 0
description: The batch number.
external_batch_id:
type: string
readOnly: true
nullable: true
minLength: 0
description: A string that uniquely identifies the external batch
batch_notes:
type: string
readOnly: true
nullable: true
default: ''
example: Batch for morning shipment
description: Custom notes you can add for each created batch
created_at:
readOnly: true
allOf:
- $ref: '#/components/schemas/date_time'
description: The date and time the batch was created in ShipEngine
processed_at:
nullable: true
readOnly: true
allOf:
- $ref: '#/components/schemas/date_time'
description: The date and time the batch was processed in ShipEngine
errors:
type: integer
format: int32
readOnly: true
minimum: 0
example: 2
description: The number of errors that occurred while generating the batch
process_errors:
errors: null
type: array
readOnly: true
items:
allOf:
- $ref: '#/components/schemas/error'
description: The errors associated with the failed API call
warnings:
type: integer
format: int32
readOnly: true
minimum: 0
example: 1
description: The number of warnings that occurred while generating the batch
completed:
type: integer
format: int32
readOnly: true
minimum: 0
example: 1
description: The number of labels generated in the batch
forms:
type: integer
format: int32
readOnly: true
minimum: 0
example: 3
description: The number of forms for customs that are available for download
count:
type: integer
format: int32
readOnly: true
minimum: 0
example: 2
description: 'The total of errors, warnings, and completed properties'
batch_shipments_url:
allOf:
- $ref: '#/components/schemas/optional_link'
description: The batch shipments endpoint
batch_labels_url:
allOf:
- $ref: '#/components/schemas/optional_link'
description: Link to batch labels query
batch_errors_url:
readOnly: true
allOf:
- $ref: '#/components/schemas/optional_link'
description: Link to batch errors endpoint
label_download:
readOnly: true
allOf:
- $ref: '#/components/schemas/label_download'
description: The label download for the batch
form_download:
readOnly: true
allOf:
- $ref: '#/components/schemas/optional_link'
description: The form download for any customs that are needed
paperless_download:
readOnly: true
allOf:
- $ref: '#/components/schemas/paperless_download'
description: >-
The paperless details which may contain elements like `href`,
`instructions` and `handoff_code`.
status:
readOnly: true
allOf:
- $ref: '#/components/schemas/batch_status'
label_layout:
title: label_layout
type: string
enum:
- 4x6
- letter
description: >
The available layouts (sizes) in which shipping labels can be
downloaded. The label format determines which sizes are supported.
`4x6` is supported for all label formats, whereas `letter` (8.5" x 11")
is only supported for `pdf` format.
label_format:
title: label_format
type: string
enum:
- pdf
- png
- zpl
description: >
The possible file formats in which shipping labels can be downloaded.
We recommend `pdf` format because it is supported by all carriers,
whereas some carriers do not support the `png` or `zpl` formats.
|Label Format | Supported Carriers
|--------------|-----------------------------------
|`pdf` | All carriers
|`png` | `fedex`
`stamps_com`
`ups`
`usps`
|`zpl` | `access_worldwide`
`apc`
`asendia`
`dhl_global_mail`
`dhl_express`
`dhl_express_australia`
`dhl_express_canada`
`dhl_express_worldwide`
`dhl_express_uk`
`dpd`
`endicia`
`fedex`
`fedex_uk`
`firstmile`
`imex`
`newgistics`
`ontrac`
`rr_donnelley`
`stamps_com`
`ups`
`usps`
se_id:
title: se_id
type: string
minLength: 1
maxLength: 25
pattern: '^se(-[a-z0-9]+)+$'
example: se-28529731
description: >-
A string that uniquely identifies a ShipEngine resource, such as a
carrier, label, shipment, etc.
label_download:
title: label_download
type: object
description: >
Reference to the various downloadable file formats for the generated
label
additionalProperties: false
properties:
href:
allOf:
- $ref: '#/components/schemas/url'
description: 'The URL of the linked resource, if any'
pdf:
allOf:
- $ref: '#/components/schemas/url'
description: The URL for the pdf generated label
png:
allOf:
- $ref: '#/components/schemas/url'
description: The URL for the png generated label
zpl:
allOf:
- $ref: '#/components/schemas/url'
description: The URL for the zpl generated label
paperless_download:
title: paperless_download
type: object
description: >
The paperless details which may contain elements like `href`,
`instructions` and `handoff_code`.
additionalProperties: false
properties:
href:
allOf:
- $ref: '#/components/schemas/url'
description: 'The URL of the linked resource, if any'
instructions:
type: string
nullable: true
default: null
description: |
The instructions for the paperless download.
handoff_code:
type: string
nullable: true
default: null
description: |
The handoff code for the paperless download.
create_batch_request:
title: create_batch_request
oneOf:
- $ref: '#/components/schemas/create_batch_request_body'
- $ref: '#/components/schemas/create_and_process_batch_request_body'
create_batch_request_body:
title: create_batch_request_body
type: object
description: A create batch request body
additionalProperties: false
properties:
external_batch_id:
allOf:
- $ref: '#/components/schemas/se_id'
description: A string that uniquely identifies the external batch
batch_notes:
type: string
minLength: 1
example: This is my batch
description: Add custom messages for a particular batch
shipment_ids:
type: array
items:
allOf:
- $ref: '#/components/schemas/se_id'
description: Array of shipment IDs used in the batch
rate_ids:
type: array
items:
type: string
minLength: 1
allOf:
- $ref: '#/components/schemas/se_id'
description: Array of rate IDs used in the batch
create_and_process_batch_request_body:
title: create_and_process_batch_request_body
type: object
description: A create and process batch request body
additionalProperties: false
properties:
external_batch_id:
allOf:
- $ref: '#/components/schemas/se_id'
description: A string that uniquely identifies the external batch
batch_notes:
type: string
minLength: 1
example: This is my batch
description: Add custom messages for a particular batch
shipment_ids:
type: array
items:
allOf:
- $ref: '#/components/schemas/se_id'
description: Array of shipment IDs used in the batch
rate_ids:
type: array
items:
type: string
minLength: 1
allOf:
- $ref: '#/components/schemas/se_id'
description: Array of rate IDs used in the batch
process_labels:
type: object
description: The information used to process the batch
properties:
create_batch_and_process_labels:
type: boolean
description: 'When ''true'', the batch will be enqueued for processing'
ship_date:
allOf:
- $ref: '#/components/schemas/date_time'
description: The Ship date the batch is being processed for
label_layout:
type: string
default: 4x6
allOf:
- $ref: '#/components/schemas/label_layout'
label_format:
default: pdf
allOf:
- $ref: '#/components/schemas/label_format'
display_scheme:
default: label
allOf:
- $ref: '#/components/schemas/display_scheme'
description: The display format that the label should be shown in.
display_scheme:
title: display_scheme
type: string
enum:
- label
- qr_code
- label_and_qr_code
- paperless
- label_and_paperless
description: The display format that the label should be shown in.
create_batch_response_body:
title: create_batch_response_body
type: object
description: A create batch response body
additionalProperties: false
allOf:
- $ref: '#/components/schemas/batch'
get_batch_by_external_id_response_body:
title: get_batch_by_external_id_response_body
type: object
description: A get batch by external id response body
additionalProperties: false
allOf:
- $ref: '#/components/schemas/batch'
get_batch_by_id_response_body:
title: get_batch_by_id_response_body
type: object
description: A get batch by id response body
additionalProperties: false
allOf:
- $ref: '#/components/schemas/batch'
add_to_batch_request_body:
title: add_to_batch_request_body
type: object
description: An add to batch request body
additionalProperties: false
allOf:
- $ref: '#/components/schemas/modify_batch'
modify_batch:
title: modify_batch
type: object
description: A modify batch object
additionalProperties: false
properties:
shipment_ids:
type: array
items:
allOf:
- $ref: '#/components/schemas/se_id'
description: The Shipment ID to be modified on the batch
description: The Shipment Ids to be modified on the batch
rate_ids:
type: array
items:
allOf:
- $ref: '#/components/schemas/se_id'
description: The Rate ID to be modified on the batch
description: Array of Rate IDs to be modifed on the batch
list_batch_errors_response_body:
title: list_batch_errors_response_body
type: object
description: A batch errors response body
required:
- errors
- links
additionalProperties: false
properties:
errors:
type: array
readOnly: true
default: []
items:
$ref: '#/components/schemas/batch_response_error'
description: The errors currently associated with the batch
links:
readOnly: true
allOf:
- $ref: '#/components/schemas/pagination_link'
batch_response_error:
title: batch_response_error
type: object
description: A batch response error
additionalProperties: false
properties:
error:
type: string
readOnly: true
minLength: 1
example: Recipient address has not been verified.
description: Error message associated with the shipment.
shipment_id:
readOnly: true
allOf:
- $ref: '#/components/schemas/se_id'
description: A string that uniquely identifies the shipment
external_shipment_id:
readOnly: true
type: string
description: An external shipment id associated with the shipment
process_batch_request_body:
title: process_batch_request_body
type: object
description: A process batch request body
additionalProperties: false
properties:
ship_date:
allOf:
- $ref: '#/components/schemas/date_time'
description: The Ship date the batch is being processed for
label_layout:
type: string
default: 4x6
allOf:
- $ref: '#/components/schemas/label_layout'
label_format:
default: pdf
allOf:
- $ref: '#/components/schemas/label_format'
display_scheme:
default: label
allOf:
- $ref: '#/components/schemas/display_scheme'
description: The display format that the label should be shown in.
remove_from_batch_request_body:
title: remove_from_batch_request_body
type: object
description: A modify batch request body
additionalProperties: false
allOf:
- $ref: '#/components/schemas/modify_batch'
get_carriers_response_body:
title: get_carriers_response_body
allOf:
- $ref: '#/components/schemas/list_carriers_response_body'
- $ref: '#/components/schemas/error_response_body'
list_carriers_response_body:
title: list_carriers_response_body
type: object
description: A carrier list response body
additionalProperties: false
required:
- carriers
properties:
carriers:
type: array
readOnly: true
items:
readOnly: true
allOf:
- $ref: '#/components/schemas/carrier'
description: The carrier response body
carrier:
title: carrier
type: object
description: |
A carrier object that represents a provider such as UPS, USPS, DHL, etc
that has been tied to the current account.
additionalProperties: false
properties:
carrier_id:
readOnly: true
allOf:
- $ref: '#/components/schemas/se_id'
description: A string that uniquely identifies the carrier.
carrier_code:
readOnly: true
allOf:
- $ref: '#/components/schemas/carrier_code'
description: >
The [shipping
carrier](https://www.shipengine.com/docs/carriers/setup/) who will
ship the package, such as `fedex`, `dhl_express`, `stamps_com`, etc.
account_number:
type: string
readOnly: true
minLength: 1
example: account_570827
description: The account number that the carrier is connected to.
requires_funded_amount:
type: boolean
readOnly: true
description: Indicates whether the carrier requires funding to use its services
balance:
type: number
format: double
readOnly: true
example: 3799.52
minimum: 0
description: Current available balance
nickname:
type: string
readOnly: true
minLength: 1
example: ShipEngine Account - Stamps.com
description: Nickname given to the account when initially setting up the carrier.
friendly_name:
type: string
readOnly: true
minLength: 1
example: Stamps.com
description: Screen readable name
primary:
type: boolean
readOnly: true
description: >-
Is this the primary carrier that is used by default when no carrier
is specified in label/shipment creation
has_multi_package_supporting_services:
type: boolean
readOnly: true
description: Carrier supports multiple packages per shipment
supports_label_messages:
type: boolean
readOnly: true
description: The carrier supports adding custom label messages to an order.
disabled_by_billing_plan:
type: boolean
readOnly: true
description: >-
The carrier is disabled by the current ShipEngine account's billing
plan.
services:
type: array
readOnly: true
items:
readOnly: true
allOf:
- $ref: '#/components/schemas/service'
description: A list of services that are offered by the carrier
packages:
type: array
readOnly: true
items:
readOnly: true
allOf:
- $ref: '#/components/schemas/package_type'
description: A list of package types that are supported by the carrier
options:
type: array
readOnly: true
items:
readOnly: true
allOf:
- $ref: '#/components/schemas/carrier_advanced_option'
description: A list of options that are available to that carrier
carrier_code:
title: carrier_code
type: string
pattern: '^[a-z0-9]+(_[a-z0-9]+)*$'
example: dhl_express
description: >
A [shipping carrier](https://www.shipengine.com/docs/carriers/setup/),
such as `fedex`, `dhl_express`, `stamps_com`, etc.
service:
title: service
type: object
description: A service offered by the carrier
additionalProperties: false
properties:
carrier_id:
readOnly: true
allOf:
- $ref: '#/components/schemas/se_id'
description: A string that uniquely identifies the carrier
carrier_code:
allOf:
- $ref: '#/components/schemas/se_id'
service_code:
type: string
minLength: 1
readOnly: true
example: usps_media_mail
description: service code
name:
type: string
minLength: 1
readOnly: true
example: USPS First Class Mail
description: User friendly service name
domestic:
type: boolean
readOnly: true
description: Supports domestic shipping
international:
type: boolean
readOnly: true
description: Supports international shipping.
is_multi_package_supported:
type: boolean
readOnly: true
description: Carrier supports multiple packages per shipment
package_type:
title: package_type
type: object
description: A package type that a carrier supports for shipment.
required:
- name
- package_code
additionalProperties: false
properties:
package_id:
allOf:
- $ref: '#/components/schemas/se_id'
description: A string that uniquely identifies the package.
package_code:
allOf:
- $ref: '#/components/schemas/package_code'
name:
type: string
minLength: 1
maxLength: 50
example: laptop_box
dimensions:
allOf:
- $ref: '#/components/schemas/dimensions'
description: The custom dimensions for the package.
description:
type: string
maxLength: 500
example: Packaging for laptops
nullable: true
description: Provides a helpful description for the custom package.
package_code:
title: package_code
type: string
minLength: 1
maxLength: 50
pattern: '^[a-z0-9]+(_[a-z0-9]+)*$'
example: small_flat_rate_box
description: >
A [package
type](https://www.shipengine.com/docs/reference/list-carrier-packages/),
such as `thick_envelope`, `small_flat_rate_box`, `large_package`, etc.
Use the code `package` for custom or unknown package types.
dimensions:
title: dimensions
type: object
description: The dimensions of a package
required:
- unit
- length
- width
- height
additionalProperties: false
properties:
unit:
default: inch
allOf:
- $ref: '#/components/schemas/dimension_unit'
length:
type: number
format: double
minimum: 0
default: 0
description: 'The length of the package, in the specified unit'
width:
type: number
format: double
minimum: 0
default: 0
description: 'The width of the package, in the specified unit'
height:
type: number
format: double
minimum: 0
default: 0
description: 'The length of the package, in the specified unit'
dimension_unit:
title: dimension_unit
type: string
enum:
- inch
- centimeter
description: The dimension units that are supported by ShipEngine.
carrier_advanced_option:
title: carrier_advanced_option
type: object
description: Advanced options that are specific to the carrier
additionalProperties: false
properties:
name:
type: string
minLength: 1
readOnly: true
example: contains_alcohol
description: Name of advanced option
default_value:
type: string
minLength: 1
readOnly: true
example: false
description: Default value of option
description:
type: string
minLength: 0
readOnly: true
description: Description of option
get_carrier_by_id_response_body:
title: get_carrier_by_id_response_body
type: object
description: A get carrier by id response body
additionalProperties: false
allOf:
- $ref: '#/components/schemas/carrier'
add_funds_to_carrier_request_body:
title: add_funds_to_carrier_request_body
type: object
description: An add funds to carrier request body
additionalProperties: false
allOf:
- $ref: '#/components/schemas/monetary_value'
monetary_value:
title: monetary_value
type: object
description: >
A monetary value, such as the price of a shipping label, the insured
value of a package, or an account balance.
required:
- currency
- amount
additionalProperties: false
properties:
currency:
allOf:
- $ref: '#/components/schemas/currency'
amount:
type: number
format: double
minimum: 0
description: 'The monetary amount, in the specified currency.'
currency:
title: currency
type: string
description: >
The currencies that are supported by ShipEngine are the ones that
specified by ISO 4217: https://www.iso.org/iso-4217-currency-codes.html
add_funds_to_carrier_response_body:
title: add_funds_to_carrier_response_body
type: object
description: The current balance of the requested carrier account
required:
- balance
additionalProperties: false
properties:
balance:
readOnly: true
allOf:
- $ref: '#/components/schemas/monetary_value'
description: The current balance of the account
get_carrier_options_response_body:
title: get_carrier_options_response_body
type: object
description: A carrier list options response body
additionalProperties: false
properties:
options:
type: array
readOnly: true
items:
readOnly: true
allOf:
- $ref: '#/components/schemas/carrier_advanced_option'
description: Carrer options
description: AN array of carrier options
list_carrier_package_types_response_body:
title: list_carrier_package_types_response_body
type: object
description: A list carrier package types response body
additionalProperties: false
properties:
packages:
type: array
readOnly: true
items:
readOnly: true
allOf:
- $ref: '#/components/schemas/package_type'
description: Custom Package Type items
description: An array of custom package types
list_carrier_services_response_body:
title: list_carrier_services_response_body
type: object
description: A carrier list services response body
additionalProperties: false
properties:
services:
type: array
readOnly: true
items:
readOnly: true
allOf:
- $ref: '#/components/schemas/service'
description: A carrier service
description: An array of services associated with the carrier
carrier_name:
title: carrier_name
type: string
enum:
- access_worldwide
- amazon_buy_shipping
- amazon_shipping_uk
- apc
- asendia
- australia_post
- canada_post
- dhl_ecommerce
- dhl_express
- dhl_express_au
- dhl_express_ca
- dhl_express_uk
- dpd
- endicia
- fedex
- fedex_uk
- firstmile
- imex
- newgistics
- ontrac
- purolator_canada
- royal_mail
- rr_donnelley
- seko
- sendle
- stamps_com
- ups
description: The shipping carriers that are supported by ShipEngine
connect_carrier_request_body:
title: connect_carrier_request_body
oneOf:
- $ref: '#/components/schemas/connect_access_worldwide_request_body'
- $ref: '#/components/schemas/connect_amazon_buy_shipping_request_body'
- $ref: '#/components/schemas/connect_amazon_shipping_uk'
- $ref: '#/components/schemas/connect_apc_request_body'
- $ref: '#/components/schemas/connect_asendia_request_body'
- $ref: '#/components/schemas/connect_australia_post_request_body'
- $ref: '#/components/schemas/connect_canada_post_request_body'
- $ref: '#/components/schemas/connect_dhl_ecommerce_request_body'
- $ref: '#/components/schemas/connect_dhl_express_request_body'
- $ref: '#/components/schemas/connect_dhl_express_au_request_body'
- $ref: '#/components/schemas/connect_dhl_express_ca_request_body'
- $ref: '#/components/schemas/connect_dhl_express_uk_request_body'
- $ref: '#/components/schemas/connect_dpd_request_body'
- $ref: '#/components/schemas/connect_endicia_request_body'
- $ref: '#/components/schemas/connect_fedex_request_body'
- $ref: '#/components/schemas/connect_fedex_uk_request_body'
- $ref: '#/components/schemas/connect_firstmile_request_body'
- $ref: '#/components/schemas/connect_imex_request_body'
- $ref: '#/components/schemas/connect_newgistics_request_body'
- $ref: '#/components/schemas/connect_ontrac_request_body'
- $ref: '#/components/schemas/connect_purolator_request_body'
- $ref: '#/components/schemas/connect_royal_mail_request_body'
- $ref: '#/components/schemas/connect_rr_donnelley_request_body'
- $ref: '#/components/schemas/connect_seko_request_body'
- $ref: '#/components/schemas/connect_sendle_request_body'
- $ref: '#/components/schemas/connect_stamps_request_body'
- $ref: '#/components/schemas/connect_ups_request_body'
connect_access_worldwide_request_body:
title: connect_access_worldwide_request_body
type: object
description: An Access Worldwide account information request body
required:
- nickname
- username
- password
additionalProperties: false
properties:
nickname:
type: string
minLength: 1
example: Stamps.com
description: The nickname associated with the carrier connection
username:
type: string
minLength: 1
description: Access Worldwide Username
password:
type: string
minLength: 1
description: Access Worldwide Password
connect_amazon_buy_shipping_request_body:
title: connect_amazon_buy_shipping_request_body
type: object
description: An Amazon account information request body
required:
- nickname
- merchant_seller_id
- email
- mws_auth_token
additionalProperties: false
properties:
nickname:
type: string
minLength: 1
example: Test Amazon Buy Shipping
description: Nickname to be associated with the account connection
merchant_seller_id:
type: string
minLength: 1
mws_auth_token:
type: string
minLength: 1
email:
allOf:
- $ref: '#/components/schemas/email'
email:
title: email
type: string
format: email
minLength: 1
example: john.doe@example.com
description: An email address.
connect_amazon_shipping_uk:
title: connect_amazon_shipping_uk
type: object
description: An Amazon Shipping UK account information request body
required:
- nickname
- auth_code
additionalProperties: false
properties:
nickname:
type: string
minLength: 1
example: Stamps.com
description: The nickname associated with the carrier connection
auth_code:
type: string
minLength: 1
description: Amazon UK Shipping auth code.
connect_apc_request_body:
title: connect_apc_request_body
type: object
description: An APC account information request body
required:
- nickname
- username
- password
additionalProperties: false
properties:
nickname:
type: string
minLength: 1
example: APC carrier account
description: The nickname for the APC account
username:
type: string
minLength: 1
example: john_doe
description: The username for the APC account
password:
type: string
minLength: 1
example: 12345
description: The password for the APC account
connect_asendia_request_body:
title: connect_asendia_request_body
type: object
description: An Asendia account information request body
required:
- nickname
- account_number
- ftp_username
- ftp_password
additionalProperties: false
properties:
nickname:
type: string
minLength: 1
example: Asendia account
description: The nickname of the Asendia account
account_number:
type: string
minLength: 1
description: Asendia account number
ftp_username:
type: string
minLength: 1
description: FTP username
ftp_password:
type: string
minLength: 1
description: FTP password
connect_australia_post_request_body:
title: connect_australia_post_request_body
type: object
description: An Australia Post account information request body
required:
- account_number
- api_key
- api_secret
- nickname
additionalProperties: false
properties:
account_number:
type: string
minLength: 1
description: Account number
api_key:
type: string
minLength: 1
description: API key
api_secret:
type: string
minLength: 1
description: API secret
nickname:
type: string
minLength: 1
description: Nickname
connect_canada_post_request_body:
title: connect_canada_post_request_body
type: object
description: A Canada Post account information request body
required:
- nickname
- api_key
- api_secret
- account_number
- contract_id
additionalProperties: false
properties:
nickname:
type: string
minLength: 1
description: Nickname
api_key:
type: string
minLength: 1
description: Canada Post Account API Key
api_secret:
type: string
minLength: 1
description: Canada Post Account API Secret
account_number:
type: string
minLength: 1
description: Canada Post Account Number
contract_id:
type: string
minLength: 1
description: Canada Post Account Contract ID
connect_dhl_ecommerce_request_body:
title: connect_dhl_ecommerce_request_body
type: object
description: A DHL Ecommerce account information request body
required:
- nickname
- client_id
- username
- password
- pickup_number
- distribution_center
additionalProperties: false
properties:
nickname:
type: string
minLength: 1
description: A nickname to help you identify this account
client_id:
type: string
minLength: 1
description: The client id
username:
type: string
minLength: 1
description: The account username
password:
type: string
minLength: 1
description: The account password
pickup_number:
type: string
minLength: 1
description: The pickup number
distribution_center:
type: string
minLength: 1
description: The distribution center
api_key:
type: string
minLength: 1
description: >
The DHL E-Commerce API key. This field is optional, but if not set
you will not be able to get rates for this account.
api_secret:
type: string
minLength: 1
description: >
The DHL E-Commerce API secret. This field is optional, but if not
set you will not be able to get rates for this account.
ancillary_endorsement:
allOf:
- $ref: '#/components/schemas/ancillary_service_endorsement'
account_number:
type: string
minLength: 1
deprecated: true
description: Account number
ftp_username:
type: string
minLength: 1
deprecated: true
description: FTP username
ftp_password:
type: string
minLength: 1
deprecated: true
description: FTP password
sold_to:
type: string
description: Sold To field
registration_id:
type: string
software_name:
type: string
ancillary_service_endorsement:
title: ancillary_service_endorsement
type: string
enum:
- none
- return_service_requested
- forwarding_service_requested
- address_service_requested
- change_service_requested
- leave_if_no_response
description: >
[Ancillary service
endorsements](https://pe.usps.com/text/qsg300/Q507.htm) are used by
mailers to request an addressee's new address and to provide the carrier
with instructions on how to handle packages that are undeliverable as
addressed.
| Ancillary Service Endorsement | Description
|--------------------------------|-----------------------------------------------------
| `none` | No ancillary service is requested.
Depending on the carrier servive, the package may be forwarded,
returned, or discarded.
| `return_service_requested` | The package is returned to the
sender. If possible, notification of the new address is is included with
the returned package.
| `forwarding_service_requested` | Forward the package to the new
address, if possible; otherwise, return it to the sender.
| `address_service_requested` | Forward the package to the new
address, if possible; otherwise, return it to the sender. This is
similar to `forwarding_service_requested`, but different restrictions
and charges may apply.
| `change_service_requested` | The package is discarded. If
possible, notification of the new address is sent to the sender.
| `leave_if_no_response` |
connect_dhl_express_request_body:
title: connect_dhl_express_request_body
type: object
description: A DHL express account information request body
required:
- nickname
- account_number
additionalProperties: false
properties:
nickname:
type: string
minLength: 1
description: Nickname
account_number:
type: string
minLength: 1
description: Account number
site_id:
type: string
minLength: 1
description: Required if password is provided
password:
type: string
minLength: 1
description: Required if site id is provided
country_code:
allOf:
- $ref: '#/components/schemas/country_code'
connect_dhl_express_au_request_body:
title: connect_dhl_express_au_request_body
type: object
description: A DHL Express AU account information request body
required:
- nickname
- account_number
additionalProperties: false
properties:
nickname:
type: string
minLength: 1
description: Nickname
account_number:
type: string
minLength: 1
description: Account number
connect_dhl_express_ca_request_body:
title: connect_dhl_express_ca_request_body
type: object
description: A DHL Express CA account information request body
required:
- nickname
- account_number
additionalProperties: false
properties:
nickname:
type: string
minLength: 1
description: Nickname
account_number:
type: string
minLength: 1
description: Account number
connect_dhl_express_uk_request_body:
title: connect_dhl_express_uk_request_body
type: object
description: A DHL Express UK account information request body
required:
- account_number
- site_id
- password
- nickname
additionalProperties: false
properties:
account_number:
type: string
minLength: 1
description: Account number
site_id:
allOf:
- $ref: '#/components/schemas/se_id'
description: A string that uniquely identifies the site
password:
type: string
minLength: 1
description: Password
nickname:
type: string
minLength: 1
description: Nickname
connect_dpd_request_body:
title: connect_dpd_request_body
type: object
description: A DPD account information request body
required:
- account_number
- password
- nickname
additionalProperties: false
properties:
account_number:
type: string
minLength: 1
description: Account number
password:
type: string
minLength: 1
description: Password
nickname:
type: string
minLength: 1
description: Nickname
connect_endicia_request_body:
title: connect_endicia_request_body
type: object
description: An Endicia account information request body
required:
- nickname
- account
- passphrase
additionalProperties: false
properties:
nickname:
type: string
minLength: 1
description: Nickname
account:
type: string
minLength: 1
description: Account
passphrase:
type: string
minLength: 1
description: Passphrase
connect_fedex_request_body:
title: connect_fedex_request_body
type: object
description: A Fedex account information request body
required:
- account_number
- address1
- city
- country_code
- email
- first_name
- last_name
- phone
- postal_code
- state
- nickname
- agree_to_eula
additionalProperties: false
properties:
account_number:
type: string
minLength: 1
description: Account number
address1:
type: string
minLength: 1
description: Address
address2:
type: string
minLength: 1
description: Address
city:
type: string
minLength: 1
description: The city
company:
type: string
minLength: 1
description: The company
country_code:
type: string
minLength: 1
description: Country code
email:
allOf:
- $ref: '#/components/schemas/email'
description: The email address
first_name:
type: string
minLength: 1
description: First name
last_name:
type: string
minLength: 1
description: Last name
phone:
type: string
minLength: 1
description: Phone number
postal_code:
type: string
minLength: 1
description: Postal Code
state:
type: string
minLength: 1
description: State
nickname:
type: string
minLength: 1
description: Nickname
agree_to_eula:
type: boolean
description: Boolean signaling agreement to the Fedex End User License Agreement
meter_number:
type: string
minLength: 1
description: Meter number
connect_fedex_uk_request_body:
title: connect_fedex_uk_request_body
type: object
description: A Fedex UK account information request body
required:
- account_number
- address1
- city
- country_code
- email
- first_name
- last_name
- phone
- postal_code
- state
- nickname
- agree_to_eula
additionalProperties: false
properties:
account_number:
type: string
minLength: 1
description: Account number
address1:
type: string
minLength: 1
description: Address
address2:
type: string
minLength: 1
description: Address
city:
type: string
minLength: 1
description: The city
company:
type: string
minLength: 1
description: The company
country_code:
type: string
minLength: 1
description: Country code
email:
allOf:
- $ref: '#/components/schemas/email'
description: The email address
first_name:
type: string
minLength: 1
description: First name
last_name:
type: string
minLength: 1
description: Last name
phone:
type: string
minLength: 1
description: Phone number
postal_code:
type: string
minLength: 1
description: Postal Code
state:
type: string
minLength: 1
description: State
nickname:
type: string
minLength: 1
description: Nickname
agree_to_eula:
type: boolean
description: Boolean signaling agreement to the Fedex End User License Agreement
meter_number:
type: string
minLength: 1
description: Meter number
connect_firstmile_request_body:
title: connect_firstmile_request_body
type: object
description: A First Mile account information request body
required:
- nickname
- mailer_id
- password
additionalProperties: false
properties:
nickname:
type: string
minLength: 1
description: Nickname
mailer_id:
allOf:
- $ref: '#/components/schemas/se_id'
description: A string that uniquely identifies the mailer
profile_name:
type: string
minLength: 1
description: Profile name
password:
type: string
minLength: 1
description: Password
connect_imex_request_body:
title: connect_imex_request_body
type: object
description: An Imex account information request body
required:
- nickname
- username
- password
additionalProperties: false
properties:
nickname:
type: string
minLength: 1
description: Nickname
username:
type: string
minLength: 1
description: Username
password:
type: string
minLength: 1
description: Password
connect_newgistics_request_body:
title: connect_newgistics_request_body
type: object
description: A Newgistics account information request body
required:
- induction_site
- nickname
additionalProperties: false
properties:
merchant_id:
type: integer
format: int32
minimum: 0
description: Merchant id
mailer_id:
type: integer
format: int32
minimum: 0
description: Mailer id
induction_site:
type: string
minLength: 1
description: Induction site
nickname:
type: string
minLength: 1
description: Nickname
connect_ontrac_request_body:
title: connect_ontrac_request_body
type: object
description: An Ontrac account information request body
required:
- nickname
- account_number
- password
additionalProperties: false
properties:
nickname:
type: string
minLength: 1
description: Nickname
account_number:
type: string
minLength: 1
description: Account number
password:
type: string
minLength: 1
description: Password
connect_purolator_request_body:
title: connect_purolator_request_body
type: object
description: A Purolator account information request body
required:
- account_number
- activation_key
- nickname
additionalProperties: false
properties:
account_number:
type: string
minLength: 1
description: Account number
activation_key:
type: string
minLength: 1
description: Activation key
nickname:
type: string
minLength: 1
description: Nickname
connect_royal_mail_request_body:
title: connect_royal_mail_request_body
type: object
description: A Royal Mail account information request body
required:
- account_number
- contact_name
- city
- postal_code
- nickname
additionalProperties: false
properties:
account_number:
type: string
minLength: 1
description: Account number
oba_email:
allOf:
- $ref: '#/components/schemas/email'
description: The oba email address
contact_name:
type: string
minLength: 1
description: Contact name
email:
allOf:
- $ref: '#/components/schemas/email'
description: The email address
company_name:
type: string
minLength: 1
description: Company name
street_line1:
type: string
minLength: 1
description: Street line1
street_line2:
type: string
minLength: 1
description: Street line2
street_line3:
type: string
minLength: 1
description: Street line3
city:
type: string
minLength: 1
description: City
postal_code:
type: string
minLength: 1
description: Postal code
phone:
type: string
minLength: 1
description: Phone
nickname:
type: string
minLength: 1
description: Nickname
connect_rr_donnelley_request_body:
title: connect_rr_donnelley_request_body
type: object
description: A RR Donnelley account information request body
required:
- nickname
- username
- password
additionalProperties: false
properties:
nickname:
type: string
minLength: 1
description: Nickname
username:
type: string
minLength: 1
description: Username
password:
type: string
minLength: 1
description: Password
connect_seko_request_body:
title: connect_seko_request_body
type: object
description: A SEKO account information request body
required:
- nickname
- access_key
additionalProperties: false
properties:
nickname:
type: string
minLength: 1
description: Nickname
access_key:
type: string
minLength: 1
description: Seko Account Access Key
connect_sendle_request_body:
title: connect_sendle_request_body
type: object
description: A Sendle account information request body
required:
- nickname
- sendle_id
- api_key
additionalProperties: false
properties:
nickname:
type: string
minLength: 1
description: Nickname
sendle_id:
allOf:
- $ref: '#/components/schemas/se_id'
description: A string that uniquely identifies the sendle
api_key:
type: string
minLength: 1
description: API key
connect_stamps_request_body:
title: connect_stamps_request_body
type: object
description: A Stamps account information request body
required:
- nickname
- username
- password
additionalProperties: false
properties:
nickname:
type: string
minLength: 1
description: Nickname
username:
type: string
minLength: 1
description: Username
password:
type: string
minLength: 1
description: Password
connect_ups_request_body:
title: connect_ups_request_body
type: object
description: A UPS account information request body
required:
- nickname
- account_number
- account_country_code
- account_postal_code
- first_name
- last_name
- company
- address1
- city
- state
- postal_code
- country_code
- email
- phone
- agree_to_technology_agreement
additionalProperties: false
properties:
nickname:
type: string
minLength: 1
description: Nickname
account_number:
type: string
minLength: 1
description: Account number
account_country_code:
type: string
minLength: 1
description: Account country code
account_postal_code:
type: string
minLength: 1
description: Account postal code
title:
type: string
minLength: 1
description: Title
first_name:
type: string
minLength: 1
description: First name
last_name:
type: string
minLength: 1
description: Last name
company:
type: string
minLength: 1
description: Company
address1:
type: string
minLength: 1
description: Address Line 1
address2:
type: string
minLength: 1
description: Address Line 2
city:
type: string
minLength: 1
description: City
state:
type: string
minLength: 1
description: State
postal_code:
type: string
minLength: 1
description: Postal code
country_code:
type: string
minLength: 1
description: Country code
email:
allOf:
- $ref: '#/components/schemas/email'
description: The email address
phone:
type: string
minLength: 1
description: Phone
invoice:
allOf:
- $ref: '#/components/schemas/ups_invoice'
description: The UPS invoice
invoice_amount:
format: double
type: number
description: The invoice amount
invoice_currency_code:
type: string
description: The invoice currency code
agree_to_technology_agreement:
type: boolean
description: >-
The Agreement to the [UPS Technology
Agreement](https://www.ups.com/assets/resources/media/UTA_with_EUR.pdf)
ups_invoice:
title: ups_invoice
type: object
description: UPS invoice
additionalProperties: false
properties:
invoice_date:
type: string
format: date-time
minLength: 1
description: invoice date
invoice_number:
type: string
minLength: 1
description: invoice number
control_id:
allOf:
- $ref: '#/components/schemas/se_id'
description: A string that uniquely identifies the control
invoice_amount:
type: number
format: double
minimum: 0
invoice_currency_code:
type: string
connect_carrier_response_body:
title: connect_carrier_response_body
type: object
description: A connect account response body
required:
- carrier_id
additionalProperties: false
properties:
carrier_id:
allOf:
- $ref: '#/components/schemas/se_id'
description: A string that uniquely identifies the carrier
carrier_name_with_settings:
title: carrier_name_with_settings
type: string
enum:
- dhl_express
- fedex
- newgistics
- ups
description: The shipping carriers for which ShipEngine supports carrier settings
get_carrier_settings_response_body:
title: get_carrier_settings_response_body
oneOf:
- $ref: '#/components/schemas/dhl_express_settings_response_body'
- $ref: '#/components/schemas/fedex_settings_response_body'
- $ref: '#/components/schemas/ups_settings_response_body'
dhl_express_settings_response_body:
title: dhl_express_settings_response_body
type: object
description: A DHL Express response body
additionalProperties: false
allOf:
- $ref: '#/components/schemas/dhl_express_account_settings'
dhl_express_account_settings:
title: dhl_express_account_settings
type: object
description: A DHL Express account settings
additionalProperties: false
properties:
nickname:
type: string
minLength: 1
description: Account nickname
should_hide_account_number_on_archive_doc:
type: boolean
description: >-
Indicates if the account number should be hidden on the archive
documentation
is_primary_account:
type: boolean
description: Indicates if this is primary account
fedex_settings_response_body:
title: fedex_settings_response_body
type: object
description: A Fedex settings response body
additionalProperties: false
allOf:
- $ref: '#/components/schemas/fedex_account_settings_request_body'
fedex_account_settings_request_body:
title: fedex_account_settings_request_body
type: object
description: A Fedex account settings request body
additionalProperties: false
allOf:
- $ref: '#/components/schemas/fedex_account_settings'
fedex_account_settings:
title: fedex_account_settings
type: object
description: A Fedex account settings request body
additionalProperties: false
properties:
nickname:
type: string
minLength: 1
description: Account nickname
pickup_type:
allOf:
- $ref: '#/components/schemas/fedex_pickup_type'
smart_post_hub:
allOf:
- $ref: '#/components/schemas/smart_post_hub'
smart_post_endorsement:
allOf:
- $ref: '#/components/schemas/ancillary_service_endorsement'
is_primary_account:
type: boolean
signature_image:
type: string
letterhead_image:
type: string
fedex_pickup_type:
title: fedex_pickup_type
type: string
enum:
- none
- regular_pickup
- request_courier
- drop_box
- business_service_center
- station
description: >
Tax identifier type for customs declaration
|Pickup Type |Description
|--------------------------|-----------------------------------------
|`none` | Not specified
|`regular_pickup` | You already have a daily pickup scheduled
with FedEx
|`request_courier` | You will call FedEx to request a courier
|`drop_box` | You will drop-off packages in a FedEx drop
box
|`business_service_center` | You will drop-off packages at an authorized
FedEx business service center
|`station` | You will drop-off the package at a FedEx
Station
smart_post_hub:
title: smart_post_hub
type: string
enum:
- none
- allentown_pa
- atlanta_ga
- baltimore_md
- charlotte_nc
- chino_ca
- dallas_tx
- denver_co
- detroit_mi
- edison_nj
- grove_city_oh
- groveport_oh
- houston_tx
- indianapolis_in
- kansas_city_ks
- los_angeles_ca
- martinsburg_wv
- memphis_tn
- minneapolis_mn
- new_berlin_wi
- northborough_ma
- orlando_fl
- phoneix_az
- pittsburgh_pa
- reno_nv
- sacramento_ca
- salt_lake_city_ut
- seattle_wa
- st_louis_mo
- windsor_ct
- newark_ny
- south_brunswick_nj
- scranton_pa
- wheeling_il
description: The possible smart post hub values
ups_settings_response_body:
title: ups_settings_response_body
type: object
description: A UPS settings response body
additionalProperties: false
allOf:
- $ref: '#/components/schemas/ups_account_settings'
ups_account_settings:
title: ups_account_settings
type: object
description: UPS account settings
additionalProperties: false
properties:
nickname:
type: string
minLength: 1
description: nickname
is_primary_account:
type: boolean
description: Indicates if this is the primary UPS account
pickup_type:
allOf:
- $ref: '#/components/schemas/ups_pickup_type'
use_carbon_neutral_shipping_program:
type: boolean
description: The use carbon neutral shipping program
use_ground_freight_pricing:
type: boolean
description: The use ground freight pricing
use_consolidation_services:
type: boolean
description: The use consolidation services
use_order_number_on_mail_innovations_labels:
type: boolean
description: The use order number on mail innovations labels
mail_innovations_endorsement:
allOf:
- $ref: '#/components/schemas/ancillary_service_endorsement'
mail_innovations_cost_center:
type: string
minLength: 0
description: mail innovations cost center
use_negotiated_rates:
type: boolean
description: The use negotiated rates
account_postal_code:
type: string
minLength: 5
description: account postal code
invoice:
allOf:
- $ref: '#/components/schemas/ups_invoice'
description: The invoice
ups_pickup_type:
title: ups_pickup_type
type: string
enum:
- daily_pickup
- occasional_pickup
- customer_counter
description: The possible ups pickup type values
update_carrier_settings_request_body:
title: update_carrier_settings_request_body
oneOf:
- $ref: '#/components/schemas/update_dhl_express_settings_request_body'
- $ref: '#/components/schemas/update_fedex_settings_request_body'
- $ref: '#/components/schemas/update_newgistics_settings_request_body'
- $ref: '#/components/schemas/update_ups_settings_request_body'
- $ref: '#/components/schemas/update_amazon_buy_shipping_request_body'
update_dhl_express_settings_request_body:
title: update_dhl_express_settings_request_body
type: object
description: An update dhl express settings request body
additionalProperties: false
allOf:
- $ref: '#/components/schemas/dhl_express_account_settings'
update_fedex_settings_request_body:
title: update_fedex_settings_request_body
type: object
description: An update Fedex settings request body
additionalProperties: false
allOf:
- $ref: '#/components/schemas/fedex_account_settings'
update_newgistics_settings_request_body:
title: update_newgistics_settings_request_body
type: object
description: A newgistics account settings request body
additionalProperties: false
properties:
include_barcode_with_order_number:
type: boolean
receive_email_on_manifest_processing:
type: boolean
update_ups_settings_request_body:
title: update_ups_settings_request_body
type: object
description: An update UPS settings request body
additionalProperties: false
allOf:
- $ref: '#/components/schemas/ups_account_settings'
update_amazon_buy_shipping_request_body:
title: update_amazon_buy_shipping_request_body
type: object
description: An amazon buy shipping account settings request body
additionalProperties: false
properties:
email:
type: string
minLength: 1
description: Email
disconnect_insurer_response_body:
title: disconnect_insurer_response_body
type: object
connect_insurer_request_body:
title: connect_insurer_request_body
type: object
description: A create shipsurance connection request body
required:
- email
- policy_id
additionalProperties: false
properties:
email:
allOf:
- $ref: '#/components/schemas/email'
policy_id:
type: string
minLength: 1
connect_insurer_response_body:
title: connect_insurer_response_body
type: object
download_file_pdf_response_body:
title: download_file_pdf_response_body
type: string
format: binary
download_file_png_response_body:
title: download_file_png_response_body
type: string
format: binary
download_file_zpl_response_body:
title: download_file_zpl_response_body
type: string
format: binary
list_webhooks_response_body:
title: list_webhooks_response_body
type: array
description: A webhook list response body
items:
allOf:
- $ref: '#/components/schemas/webhook'
description: The webhook list response body
webhook:
title: webhook
type: object
description: A webhook
additionalProperties: false
properties:
webhook_id:
readOnly: true
allOf:
- $ref: '#/components/schemas/se_id'
description: A string that uniquely identifies the webhook
url:
allOf:
- $ref: '#/components/schemas/url'
example: 'https://[YOUR ENDPOINT ID].x.requestbin.com'
description: The url that the webhook sends the request to
event:
allOf:
- $ref: '#/components/schemas/webhook_event'
headers:
type: array
items:
allOf:
- $ref: '#/components/schemas/webhook_header'
description: Array of custom webhook headers
webhook_event:
title: webhook_event
type: string
enum:
- batch
- carrier_connected
- order_source_refresh_complete
- rate
- report_complete
- sales_orders_imported
- track
description: The possible webook event values
webhook_header:
title: webhook_header
type: object
description: Optional header to be specified in webhook
properties:
key:
$ref: '#/components/schemas/key'
value:
$ref: '#/components/schemas/value'
required:
- key
- value
key:
title: key
type: string
min_length: 1
description: Key/name of a header
example: custom-key
value:
title: value
type: string
description: Value of a header
example: custom-value
create_webhook_request_body:
title: create_webhook_request_body
type: object
description: A create webhook request body
required:
- event
- url
additionalProperties: false
properties:
event:
allOf:
- $ref: '#/components/schemas/webhook_event'
url:
allOf:
- $ref: '#/components/schemas/url'
example: 'https://[YOUR ENDPOINT ID].x.requestbin.com'
description: The url that the webhook sends the request to
headers:
type: array
items:
allOf:
- $ref: '#/components/schemas/webhook_header'
description: Array of custom webhook headers
create_webhook_response_body:
title: create_webhook_response_body
type: object
description: A webhook response body
additionalProperties: false
required:
- webhook_id
- url
- event
allOf:
- $ref: '#/components/schemas/webhook'
get_webhook_by_id_response_body:
title: get_webhook_by_id_response_body
type: object
description: A get webhook id response body
additionalProperties: false
required:
- webhook_id
- url
- event
allOf:
- $ref: '#/components/schemas/webhook'
update_webhook_request_body:
title: update_webhook_request_body
type: object
description: An update webhook request body
additionalProperties: false
properties:
url:
allOf:
- $ref: '#/components/schemas/url'
example: 'https://[YOUR ENDPOINT ID].x.requestbin.com'
description: The url that the wehbook sends the request
headers:
type: array
items:
allOf:
- $ref: '#/components/schemas/webhook_header'
description: Array of custom webhook headers
add_funds_to_insurance_request_body:
title: add_funds_to_insurance_request_body
type: object
description: An add funds to insurance request body
additionalProperties: false
allOf:
- $ref: '#/components/schemas/monetary_value'
add_funds_to_insurance_response_body:
title: add_funds_to_insurance_response_body
type: object
description: Add funds to insurance response body
additionalProperties: false
allOf:
- $ref: '#/components/schemas/monetary_value'
get_insurance_balance_response_body:
title: get_insurance_balance_response_body
type: object
description: A get insurance balance response body
additionalProperties: false
allOf:
- $ref: '#/components/schemas/monetary_value'
label_status:
title: label_status
type: string
enum:
- processing
- completed
- error
- voided
description: >
The possible statuses that a [shipping
label](https://www.shipengine.com/docs/labels/create-a-label/) can be
in.
|Status |Description
|:------------|:-----------------------------------------------------
|`processing` |When labels are created in a
[batch](https://www.shipengine.com/docs/labels/bulk/), it may take a few
minutes for all of the labels in the batch to be created. During this
period, they will be in `processing` status.
|`completed` |The label was successfully created
|`error` |The label could not be created due to an error, such as
an invalid delivery address
|`voided` |The label has been
[voided](https://www.shipengine.com/docs/labels/voiding/)
service_code:
title: service_code
type: string
pattern: '^[a-z0-9]+(_[a-z0-9-]+)* ?$'
example: usps_first_class_mail
description: >
A [carrier
service](https://www.shipengine.com/docs/shipping/use-a-carrier-service/),
such as `fedex_ground`, `usps_first_class_mail`, `flat_rate_envelope`,
etc.
list_labels_response_body:
title: list_labels_response_body
type: object
description: A list label response body
required:
- labels
additionalProperties: false
properties:
labels:
type: array
minItems: 0
description: >
The labels that matched the query criteria. If no matching labels
were found, then this array is empty; otherwise, it contains one
page of results. The last page of results may have fewer labels
than the `page_size`.
items:
title: label
type: object
description: >
A label represents the physical sticker that you affix to a
package to ship it. ShipEngine makes it easy for you to [create
labels](https://www.shipengine.com/docs/labels/create-a-label/)
and then download them in PDF, PNG, or ZPL format so you can print
them.
additionalProperties: false
properties:
label_id:
readOnly: true
allOf:
- $ref: '#/components/schemas/se_id'
description: >
A string that uniquely identifies the label. This ID is
generated by ShipEngine when the label is created.
status:
readOnly: true
allOf:
- $ref: '#/components/schemas/label_status'
shipment_id:
readOnly: true
allOf:
- $ref: '#/components/schemas/se_id'
description: >
The shipment that this label is for. ShipEngine can create a
shipment for you automatically when you [create a
label](https://www.shipengine.com/docs/labels/create-a-label/),
or you can [create your own
shipment](https://www.shipengine.com/docs/shipping/create-a-shipment/)
and then [use it to print a
label](https://www.shipengine.com/docs/labels/create-from-shipment/)
shipment:
writeOnly: true
allOf:
- $ref: '#/components/schemas/shipment'
description: The shipment information used to generate the label
ship_date:
allOf:
- $ref: '#/components/schemas/date'
readOnly: true
description: >
The date that the package was (or will be) shippped.
ShipEngine will take the day of week into consideration. For
example, if the carrier does not operate on Sundays, then a
package that would have shipped on Sunday will ship on Monday
instead.
created_at:
readOnly: true
allOf:
- $ref: '#/components/schemas/date_time'
description: The date and time that the label was created in ShipEngine.
shipment_cost:
readOnly: true
allOf:
- $ref: '#/components/schemas/monetary_value'
description: >
The cost of shipping, delivery confirmation, and other carrier
charges. This amount **does not** include insurance costs.
insurance_cost:
readOnly: true
allOf:
- $ref: '#/components/schemas/monetary_value'
description: >
The insurance cost for this package. Add this to the
`shipment_cost` field to get the total cost.
requested_comparison_amount:
readOnly: true
allOf:
- $ref: '#/components/schemas/monetary_value'
description: >
The total shipping cost for the specified
comparison_rate_type.
tracking_number:
type: string
minLength: 1
readOnly: true
example: '782758401696'
description: >-
The tracking number for the package. Tracking number formats
vary across carriers.
is_return_label:
type: boolean
description: >
Indicates whether this is a return label. You may also want
to set the `rma_number` so you know what is being returned.
rma_number:
type: string
nullable: true
description: >
An optional Return Merchandise Authorization number. This
field is useful for return labels. You can set it to any
string value.
is_international:
type: boolean
readOnly: true
description: >
Indicates whether this is an international shipment. That is,
the originating country and destination country are different.
batch_id:
readOnly: true
allOf:
- $ref: '#/components/schemas/se_id'
description: >
If this label was created as part of a
[batch](https://www.shipengine.com/docs/labels/bulk/), then
this is the unique ID of that batch.
carrier_id:
readOnly: true
allOf:
- $ref: '#/components/schemas/se_id'
description: >
The unique ID of the [carrier
account](https://www.shipengine.com/docs/carriers/setup/) that
was used to create this label
charge_event:
allOf:
- $ref: '#/components/schemas/label_charge_event'
description: |
The label charge event.
outbound_label_id:
allOf:
- $ref: '#/components/schemas/se_id'
writeOnly: true
description: >
The `label_id` of the original (outgoing) label that the
return label is for. This associates the two labels together,
which is
required by some carriers.
service_code:
allOf:
- $ref: '#/components/schemas/service_code'
readOnly: true
description: >
The [carrier
service](https://www.shipengine.com/docs/shipping/use-a-carrier-service/)
used to ship the package, such as `fedex_ground`,
`usps_first_class_mail`, `flat_rate_envelope`, etc.
test_label:
writeOnly: true
type: boolean
default: false
deprecated: true
description: >-
Indicate if this label is being used only for testing
purposes. If true, then no charge will be added to your
account.
package_code:
readOnly: true
allOf:
- $ref: '#/components/schemas/package_code'
description: >
The [package
type](https://www.shipengine.com/docs/reference/list-carrier-packages/),
such as `thick_envelope`, `small_flat_rate_box`,
`large_package`, etc. The code `package` indicates a custom
or unknown package type.
validate_address:
writeOnly: true
default: validate_and_clean
allOf:
- $ref: '#/components/schemas/validate_address'
voided:
type: boolean
readOnly: true
description: >
Indicates whether the label has been
[voided](https://www.shipengine.com/docs/labels/voiding/)
voided_at:
nullable: true
readOnly: true
allOf:
- $ref: '#/components/schemas/date_time'
description: >
The date and time that the label was
[voided](https://www.shipengine.com/docs/labels/voiding/), or
`null` if the label has not been voided
label_download_type:
writeOnly: true
default: url
allOf:
- $ref: '#/components/schemas/label_download_type'
label_format:
default: pdf
allOf:
- $ref: '#/components/schemas/label_format'
description: >
The file format that you want the label to be in. We
recommend `pdf` format because it is supported by all
carriers, whereas some carriers do not support the `png` or
`zpl` formats.
display_scheme:
default: label
allOf:
- $ref: '#/components/schemas/display_scheme'
description: The display format that the label should be shown in.
label_layout:
default: 4x6
allOf:
- $ref: '#/components/schemas/label_layout'
description: >
The layout (size) that you want the label to be in. The
`label_format` determines which sizes are allowed. `4x6` is
supported for all label formats, whereas `letter` (8.5" x 11")
is only supported for `pdf` format.
trackable:
type: boolean
readOnly: true
description: >
Indicates whether the shipment is trackable, in which case the
`tracking_status` field will reflect the current status and
each package will have a `tracking_number`.
label_image_id:
nullable: true
allOf:
- $ref: '#/components/schemas/image_id'
description: >-
The label image resource that was used to create a custom
label image.
carrier_code:
readOnly: true
allOf:
- $ref: '#/components/schemas/carrier_code'
description: >
The [shipping
carrier](https://www.shipengine.com/docs/carriers/setup/) who
will ship the package, such as `fedex`, `dhl_express`,
`stamps_com`, etc.
tracking_status:
readOnly: true
allOf:
- $ref: '#/components/schemas/tracking_status'
description: >-
The current status of the package, such as `in_transit` or
`delivered`
label_download:
allOf:
- $ref: '#/components/schemas/label_download'
readOnly: true
form_download:
readOnly: true
nullable: true
allOf:
- $ref: '#/components/schemas/link'
description: >
The link to download the customs form (a.k.a. commercial
invoice) for this shipment, if any. Forms are in PDF format.
This field is null if the shipment does not require a customs
form, or if the carrier does not support it.
paperless_download:
readOnly: true
nullable: true
allOf:
- $ref: '#/components/schemas/paperless_download'
description: >
The paperless details which may contain elements like `href`,
`instructions` and `handoff_code`.
insurance_claim:
readOnly: true
nullable: true
allOf:
- $ref: '#/components/schemas/link'
description: >
The link to submit an insurance claim for the shipment. This
field is null if the shipment is not insured or if the
insurance provider does not support online claim submission.
packages:
type: array
readOnly: true
description: >
The label's package(s).
> **Note:** Some carriers only allow one package per label.
If you attempt to create a multi-package label for a carrier
that doesn't allow it, an error will be returned.
items:
allOf:
- $ref: '#/components/schemas/package'
- $ref: '#/components/schemas/alternative_identifiers'
alternative_identifiers:
type: array
readOnly: true
nullable: true
description: >
Additional information some carriers may provide by which to
identify a given label in their system.
items:
$ref: '#/components/schemas/alternative_identifier'
allOf:
- $ref: '#/components/schemas/paged_list_response_body'
create_label_request_body:
title: create_label_request_body
type: object
description: A purchase label request body
required:
- shipment
additionalProperties: false
allOf:
- $ref: '#/components/schemas/label'
properties:
ship_to_service_point_id:
nullable: true
type: string
description: >-
A unique identifier for a carrier service point where the shipment
will be delivered by the carrier. This will take precedence over a
shipment's ship to address.
example: '614940'
ship_from_service_point_id:
nullable: true
type: string
description: >-
A unique identifier for a carrier drop off point where a merchant
plans to deliver packages. This will take precedence over a
shipment's ship from address.
example: '614940'
label:
title: label
type: object
description: >
A label represents the physical sticker that you affix to a package to
ship it. ShipEngine makes it easy for you to [create
labels](https://www.shipengine.com/docs/labels/create-a-label/) and then
download them in PDF, PNG, or ZPL format so you can print them.
additionalProperties: false
properties:
label_id:
readOnly: true
allOf:
- $ref: '#/components/schemas/se_id'
description: >
A string that uniquely identifies the label. This ID is generated by
ShipEngine when the label is created.
status:
readOnly: true
allOf:
- $ref: '#/components/schemas/label_status'
shipment_id:
readOnly: true
allOf:
- $ref: '#/components/schemas/se_id'
description: >
The shipment that this label is for. ShipEngine can create a
shipment for you automatically when you [create a
label](https://www.shipengine.com/docs/labels/create-a-label/), or
you can [create your own
shipment](https://www.shipengine.com/docs/shipping/create-a-shipment/)
and then [use it to print a
label](https://www.shipengine.com/docs/labels/create-from-shipment/)
shipment:
writeOnly: true
allOf:
- $ref: '#/components/schemas/shipment'
description: The shipment information used to generate the label
ship_date:
allOf:
- $ref: '#/components/schemas/date'
readOnly: true
description: >
The date that the package was (or will be) shippped. ShipEngine
will take the day of week into consideration. For example, if the
carrier does not operate on Sundays, then a package that would have
shipped on Sunday will ship on Monday instead.
created_at:
readOnly: true
allOf:
- $ref: '#/components/schemas/date_time'
description: The date and time that the label was created in ShipEngine.
shipment_cost:
readOnly: true
allOf:
- $ref: '#/components/schemas/monetary_value'
description: >
The cost of shipping, delivery confirmation, and other carrier
charges. This amount **does not** include insurance costs.
insurance_cost:
readOnly: true
allOf:
- $ref: '#/components/schemas/monetary_value'
description: >
The insurance cost for this package. Add this to the
`shipment_cost` field to get the total cost.
requested_comparison_amount:
readOnly: true
allOf:
- $ref: '#/components/schemas/monetary_value'
description: |
The total shipping cost for the specified comparison_rate_type.
tracking_number:
type: string
minLength: 1
readOnly: true
example: '782758401696'
description: >-
The tracking number for the package. Tracking number formats vary
across carriers.
is_return_label:
type: boolean
description: >
Indicates whether this is a return label. You may also want to set
the `rma_number` so you know what is being returned.
rma_number:
type: string
nullable: true
description: >
An optional Return Merchandise Authorization number. This field is
useful for return labels. You can set it to any string value.
is_international:
type: boolean
readOnly: true
description: >
Indicates whether this is an international shipment. That is, the
originating country and destination country are different.
batch_id:
readOnly: true
allOf:
- $ref: '#/components/schemas/se_id'
description: >
If this label was created as part of a
[batch](https://www.shipengine.com/docs/labels/bulk/), then this is
the unique ID of that batch.
carrier_id:
readOnly: true
allOf:
- $ref: '#/components/schemas/se_id'
description: >
The unique ID of the [carrier
account](https://www.shipengine.com/docs/carriers/setup/) that was
used to create this label
charge_event:
allOf:
- $ref: '#/components/schemas/label_charge_event'
description: |
The label charge event.
outbound_label_id:
allOf:
- $ref: '#/components/schemas/se_id'
writeOnly: true
description: >
The `label_id` of the original (outgoing) label that the return
label is for. This associates the two labels together, which is
required by some carriers.
service_code:
allOf:
- $ref: '#/components/schemas/service_code'
readOnly: true
description: >
The [carrier
service](https://www.shipengine.com/docs/shipping/use-a-carrier-service/)
used to ship the package, such as `fedex_ground`,
`usps_first_class_mail`, `flat_rate_envelope`, etc.
test_label:
writeOnly: true
type: boolean
default: false
deprecated: true
description: >-
Indicate if this label is being used only for testing purposes. If
true, then no charge will be added to your account.
package_code:
readOnly: true
allOf:
- $ref: '#/components/schemas/package_code'
description: >
The [package
type](https://www.shipengine.com/docs/reference/list-carrier-packages/),
such as `thick_envelope`, `small_flat_rate_box`, `large_package`,
etc. The code `package` indicates a custom or unknown package type.
validate_address:
writeOnly: true
default: validate_and_clean
allOf:
- $ref: '#/components/schemas/validate_address'
voided:
type: boolean
readOnly: true
description: >
Indicates whether the label has been
[voided](https://www.shipengine.com/docs/labels/voiding/)
voided_at:
nullable: true
readOnly: true
allOf:
- $ref: '#/components/schemas/date_time'
description: >
The date and time that the label was
[voided](https://www.shipengine.com/docs/labels/voiding/), or `null`
if the label has not been voided
label_download_type:
writeOnly: true
default: url
allOf:
- $ref: '#/components/schemas/label_download_type'
label_format:
default: pdf
allOf:
- $ref: '#/components/schemas/label_format'
description: >
The file format that you want the label to be in. We recommend
`pdf` format because it is supported by all carriers, whereas some
carriers do not support the `png` or `zpl` formats.
display_scheme:
default: label
allOf:
- $ref: '#/components/schemas/display_scheme'
description: The display format that the label should be shown in.
label_layout:
default: 4x6
allOf:
- $ref: '#/components/schemas/label_layout'
description: >
The layout (size) that you want the label to be in. The
`label_format` determines which sizes are allowed. `4x6` is
supported for all label formats, whereas `letter` (8.5" x 11") is
only supported for `pdf` format.
trackable:
type: boolean
readOnly: true
description: >
Indicates whether the shipment is trackable, in which case the
`tracking_status` field will reflect the current status and each
package will have a `tracking_number`.
label_image_id:
nullable: true
allOf:
- $ref: '#/components/schemas/image_id'
description: >-
The label image resource that was used to create a custom label
image.
carrier_code:
readOnly: true
allOf:
- $ref: '#/components/schemas/carrier_code'
description: >
The [shipping
carrier](https://www.shipengine.com/docs/carriers/setup/) who will
ship the package, such as `fedex`, `dhl_express`, `stamps_com`, etc.
tracking_status:
readOnly: true
allOf:
- $ref: '#/components/schemas/tracking_status'
description: >-
The current status of the package, such as `in_transit` or
`delivered`
label_download:
allOf:
- $ref: '#/components/schemas/label_download'
readOnly: true
form_download:
readOnly: true
nullable: true
allOf:
- $ref: '#/components/schemas/link'
description: >
The link to download the customs form (a.k.a. commercial invoice)
for this shipment, if any. Forms are in PDF format. This field is
null if the shipment does not require a customs form, or if the
carrier does not support it.
paperless_download:
readOnly: true
nullable: true
allOf:
- $ref: '#/components/schemas/paperless_download'
description: >
The paperless details which may contain elements like `href`,
`instructions` and `handoff_code`.
insurance_claim:
readOnly: true
nullable: true
allOf:
- $ref: '#/components/schemas/link'
description: >
The link to submit an insurance claim for the shipment. This field
is null if the shipment is not insured or if the insurance provider
does not support online claim submission.
packages:
type: array
readOnly: true
description: >
The label's package(s).
> **Note:** Some carriers only allow one package per label. If you
attempt to create a multi-package label for a carrier that doesn't
allow it, an error will be returned.
items:
allOf:
- $ref: '#/components/schemas/package'
- $ref: '#/components/schemas/alternative_identifiers'
alternative_identifiers:
type: array
readOnly: true
nullable: true
description: >
Additional information some carriers may provide by which to
identify a given label in their system.
items:
$ref: '#/components/schemas/alternative_identifier'
shipment:
title: shipment
type: object
description: >
The information necessary to ship a package, such as the origin, the
destination, the carrier service, and the package dimensions and weight.
> **Note:** Either `ship_from` or `warehouse_id` must be set.
required:
- shipment_id
- carrier_id
- service_code
- ship_date
- created_at
- modified_at
- shipment_status
- ship_to
- ship_from
- warehouse_id
- return_to
- confirmation
- customs
- advanced_options
- insurance_provider
- tags
- packages
- total_weight
additionalProperties: false
allOf:
- $ref: '#/components/schemas/partial_shipment'
partial_shipment:
title: partial_shipment
type: object
description: >
The information necessary to ship a package, such as the origin, the
destination, the carrier service, and the package dimensions and weight.
additionalProperties: false
properties:
shipment_id:
readOnly: true
allOf:
- $ref: '#/components/schemas/se_id'
description: A string that uniquely identifies the shipment
carrier_id:
allOf:
- $ref: '#/components/schemas/se_id'
description: The carrier account that is billed for the shipping charges
service_code:
allOf:
- $ref: '#/components/schemas/service_code'
description: >
The [carrier
service](https://www.shipengine.com/docs/shipping/use-a-carrier-service/)
used to ship the package, such as `fedex_ground`,
`usps_first_class_mail`, `flat_rate_envelope`, etc.
external_order_id:
type: string
nullable: true
description: ID that the Order Source assigned
items:
type: array
default: []
items:
allOf:
- $ref: '#/components/schemas/shipment_item'
description: >
Describe the packages included in this shipment as related to
potential metadata that was imported from
external order sources
tax_identifiers:
type: array
nullable: true
items:
allOf:
- $ref: '#/components/schemas/tax_identifier'
external_shipment_id:
type: string
maxLength: 50
nullable: true
description: >
A unique user-defined key to identify a shipment. This can be used
to retrieve the shipment.
> **Warning:** The `external_shipment_id` is limited to 50
characters. Any additional characters will be truncated.
shipment_number:
type: string
maxLength: 50
nullable: true
description: >
A non-unique user-defined number used to identify a shipment. If
undefined, this will match the external_shipment_id of the shipment.
> **Warning:** The `shipment_number` is limited to 50 characters.
Any additional characters will be truncated.
ship_date:
allOf:
- $ref: '#/components/schemas/date'
description: >
The date that the shipment was (or will be) shippped. ShipEngine
will take the day of week into consideration. For example, if the
carrier does not operate on Sundays, then a package that would have
shipped on Sunday will ship on Monday instead.
created_at:
readOnly: true
allOf:
- $ref: '#/components/schemas/date_time'
description: The date and time that the shipment was created in ShipEngine.
modified_at:
readOnly: true
allOf:
- $ref: '#/components/schemas/date_time'
description: The date and time that the shipment was created or last modified.
shipment_status:
readOnly: true
default: pending
allOf:
- $ref: '#/components/schemas/shipment_status'
description: The current status of the shipment
ship_to:
allOf:
- $ref: '#/components/schemas/shipping_address_to'
description: The recipient's mailing address
ship_from:
allOf:
- $ref: '#/components/schemas/shipping_address'
description: >
The shipment's origin address. If you frequently ship from the same
location, consider [creating a
warehouse](https://www.shipengine.com/docs/reference/create-warehouse/).
Then you can simply specify the `warehouse_id` rather than the
complete address each time.
warehouse_id:
nullable: true
default: null
allOf:
- $ref: '#/components/schemas/se_id'
description: >
The
[warehouse](https://www.shipengine.com/docs/shipping/ship-from-a-warehouse/)
that the shipment is being shipped from. Either `warehouse_id` or
`ship_from` must be specified.
return_to:
allOf:
- $ref: '#/components/schemas/shipping_address'
description: >
The return address for this shipment. Defaults to the `ship_from`
address.
is_return:
type: boolean
nullable: true
default: false
description: >
An optional indicator if the shipment is intended to be a return.
Defaults to false if not provided.
confirmation:
default: none
allOf:
- $ref: '#/components/schemas/delivery_confirmation'
description: >-
The type of delivery confirmation that is required for this
shipment.
customs:
nullable: true
default: null
allOf:
- $ref: '#/components/schemas/international_shipment_options'
description: >
Customs information. This is usually only needed for international
shipments.
advanced_options:
allOf:
- $ref: '#/components/schemas/advanced_shipment_options'
description: Advanced shipment options. These are entirely optional.
insurance_provider:
default: none
allOf:
- $ref: '#/components/schemas/insurance_provider'
description: >
The insurance provider to use for any insured packages in the
shipment.
tags:
type: array
readOnly: true
default: []
minItems: 0
items:
allOf:
- $ref: '#/components/schemas/tag'
description: >
Arbitrary tags associated with this shipment. Tags can be used to
categorize shipments, and shipments can be queried by their tags.
order_source_code:
allOf:
- $ref: '#/components/schemas/order_source_name'
packages:
type: array
minItems: 1
items:
allOf:
- $ref: '#/components/schemas/package'
description: >
The packages in the shipment.
> **Note:** Some carriers only allow one package per shipment. If
you attempt to create a multi-package shipment for a carrier that
doesn't allow it, an error will be returned.
total_weight:
readOnly: true
allOf:
- $ref: '#/components/schemas/weight'
description: The combined weight of all packages in the shipment
comparison_rate_type:
nullable: true
type: string
description: >-
Calculate a rate for this shipment with the requested carrier using
a ratecard that differs from the default. Only supported for UPS
and USPS.
example: retail
shipment_item:
title: shipment_item
type: object
description: A shipment item
additionalProperties: false
properties:
name:
type: string
minLength: 0
description: item name
sales_order_id:
type: string
nullable: true
description: sales order id
sales_order_item_id:
type: string
nullable: true
description: sales order item id
quantity:
type: integer
format: int32
minimum: 0
description: The quantity of this item included in the shipment
sku:
type: string
nullable: true
description: Item Stock Keeping Unit
external_order_id:
type: string
nullable: true
description: external order id
external_order_item_id:
type: string
nullable: true
description: external order item id
asin:
type: string
nullable: true
minLength: 10
maxLength: 10
example: B00005N5PF
description: Amazon Standard Identification Number
order_source_code:
allOf:
- $ref: '#/components/schemas/order_source_name'
order_source_name:
title: order_source_name
type: string
enum:
- amazon_ca
- amazon_us
- brightpearl
- channel_advisor
- cratejoy
- ebay
- etsy
- jane
- groupon_goods
- magento
- paypal
- seller_active
- shopify
- stitch_labs
- squarespace
- three_dcart
- tophatter
- walmart
- woo_commerce
- volusion
description: The order sources that are supported by ShipEngine
tax_identifier:
title: tax_identifier
type: object
description: A tax identifier object
additionalProperties: false
required:
- taxable_entity_type
- identifier_type
- issuing_authority
- value
properties:
taxable_entity_type:
allOf:
- $ref: '#/components/schemas/taxable_entity_type'
identifier_type:
allOf:
- $ref: '#/components/schemas/identifier_type'
issuing_authority:
type: string
description: >-
The authority that issued this tax. This must be a valid 2 character
ISO 3166 Alpha 2 country code.
value:
type: string
description: The value of the identifier
taxable_entity_type:
title: taxable_entity_type
type: string
enum:
- shipper
- recipient
- ior
description: >
The taxable entity type for this tax item. Valid values include the
following
|Value |Description
|:--------- |:-----------------------------------------------------
|`shipper` | The shipper is responsible for this tax.
|`recipient` | The recipient of the shipment is responsible for this
tax.
|`ior` | The importer of records is responsible for tax.
identifier_type:
title: identifier_type
type: string
enum:
- vat
- eori
- ssn
- ein
- tin
- ioss
- pan
- voec
- pccc
- oss
- passport
- abn
description: >
Tax identifier type for customs declaration
|Pickup Type | Description
|---------------|-----------------------------------------
|`vat` | The tax identifier is a Value Added Tax.
|`eori` | The tax identifier is an Economic Operators
Registration and Identification Number (EORI).
|`ssn` | The tax identifier is a Social Security Number.
|`ein` | The tax identifier is an Employer Identification
Number (EIN).
|`tin` | The tax identifier is a Tax Identification Number
(TIN).
|`ioss` | The tax identifier is an Import One-Stop Shop (IOSS).
|`pan` | The tax identifier is a Permanent Account Number
(PAN).
|`voec` | The tax identifier is a Norwegian VAT On
E-Commerce(VOEC).
|`pccc` | The tax identifier is a Personal Customs Clearance
Code (PCCC).
|`oss` | The tax identifier is an One-Stop Shop (OSS).
|`passport` | The tax identifier is a Passport Number.
|`abn` | The tax identifier is an Australian Business Number.
date:
title: date
type: string
format: date-time
pattern: '^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[-+]\d{2}:\d{2}))?$'
example: '2018-09-23T00:00:00.000Z'
description: >
An [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) string that
represents a date, but not a specific time. The value _may_ contain a
time component, but it will be set to `00:00:00` UTC by ShipEngine.
shipment_status:
title: shipment_status
type: string
enum:
- pending
- processing
- label_purchased
- cancelled
description: The possible shipment status values
shipping_address_to:
title: shipping_address_to
type: object
additionalProperties: false
allOf:
- $ref: '#/components/schemas/address'
- $ref: '#/components/schemas/partial_shipping_address_to'
partial_shipping_address_to:
title: partial_shipping_address_to
type: object
description: A complete or partial mailing address.
additionalProperties: false
properties:
instructions:
type: string
minLength: 1
nullable: true
description: |
Additional text about how to handle the shipment at this address.
geolocation:
type: array
items:
type: object
properties:
type:
type: string
example: what3words
description: |
Enum of available type of geolocation items:
- 'what3words' functionality allows to specify a location by providing 3 words that have been assign to the specific location see [link](https://what3words.com/business) for more details.
enum:
- what3words
value:
type: string
example: cats.with.thumbs
description: value of the geolocation item
shipping_address:
title: shipping_address
type: object
additionalProperties: false
allOf:
- $ref: '#/components/schemas/address'
- $ref: '#/components/schemas/partial_shipping_address'
partial_shipping_address:
title: partial_shipping_address
type: object
description: A complete or partial mailing address.
additionalProperties: false
properties:
instructions:
type: string
minLength: 1
nullable: true
description: |
Additional text about how to handle the shipment at this address.
delivery_confirmation:
title: delivery_confirmation
type: string
enum:
- none
- delivery
- signature
- adult_signature
- direct_signature
- delivery_mailed
- verbal_confirmation
description: The possible delivery confirmation values
international_shipment_options:
title: international_shipment_options
type: object
description: 'Options for international shipments, such as customs declarations.'
required:
- contents
- non_delivery
additionalProperties: false
properties:
contents:
default: merchandise
allOf:
- $ref: '#/components/schemas/package_contents'
description: >-
The type of contents in this shipment. This may impact import
duties or customs treatment.
contents_explanation:
type: string
description: >-
Explanation for contents (required if the `contents` is provided as
`other`)
non_delivery:
default: return_to_sender
allOf:
- $ref: '#/components/schemas/non_delivery'
description: Indicates what to do if a package is unable to be delivered.
terms_of_trade_code:
type: string
description: Specifies the supported terms of trade code (incoterms)
allOf:
- $ref: '#/components/schemas/Allowed incoterms'
declaration:
type: string
description: Declaration statement to be placed on the commercial invoice
invoice_additional_details:
type: object
allOf:
- $ref: '#/components/schemas/invoice_additional_details'
importer_of_record:
type: object
allOf:
- $ref: '#/components/schemas/importer_of_records'
customs_items:
deprecated: true
type: array
default: []
minItems: 0
description: >-
Customs declarations for each item in the shipment. (Please provide
this information under `products` inside `packages`)
items:
$ref: '#/components/schemas/customs_item'
package_contents:
title: package_contents
type: string
enum:
- merchandise
- documents
- gift
- returned_goods
- sample
- other
description: The possible package contents values
non_delivery:
title: non_delivery
type: string
enum:
- return_to_sender
- treat_as_abandoned
description: The possible non delivery values
Allowed incoterms:
title: Allowed incoterms
type: string
enum:
- exw
- fca
- cpt
- cip
- dpu
- dap
- ddp
- fas
- fob
- cfr
- cif
- ddu
- daf
- deq
- des
invoice_additional_details:
title: invoice_additional_details
type: object
description: |
The additional information to put on commercial invoice
properties:
freight_charge:
allOf:
- $ref: '#/components/schemas/monetary_value'
description: Freight Charge for shipment.
insurance_charge:
allOf:
- $ref: '#/components/schemas/monetary_value'
description: Insurance Charge for shipment.
discount:
allOf:
- $ref: '#/components/schemas/monetary_value'
description: Discount for shipment.
other_charge:
allOf:
- $ref: '#/components/schemas/monetary_value'
description: Other charge for shipment.
other_charge_description:
type: string
description: Description for the other charge (if provided).
importer_of_records:
title: importer_of_records
type: object
description: |
importer of records address, anywhere in the world.
required:
- name
- address_line1
- city_locality
- postal_code
- country_code
properties:
name:
type: string
minLength: 1
example: John Doe
description: >
The name of a contact person at this address. Either `name` or the
`company_name` field should always be set.
phone:
type: string
minLength: 1
example: +1 204-253-9411 ext. 123
description: >
The phone number of a contact person at this address. The format of
this phone number varies depending on the country.
email:
type: string
nullable: true
example: example@example.com
description: |
Email for the address owner.
company_name:
type: string
minLength: 1
nullable: true
example: The Home Depot
description: >
If this is a business address, then the company name should be
specified here. Either `name` or the `company_name` field should
always be set.
address_line1:
type: string
minLength: 1
example: 1999 Bishop Grandin Blvd.
description: >
The first line of the street address. For some addresses, this may
be the only line. Other addresses may require 2 or 3 lines.
address_line2:
type: string
minLength: 1
nullable: true
example: Unit 408
description: >
The second line of the street address. For some addresses, this
line may not be needed.
address_line3:
type: string
minLength: 1
nullable: true
example: 'Building #7'
description: >
The third line of the street address. For some addresses, this line
may not be needed.
city_locality:
type: string
minLength: 1
example: Winnipeg
description: The name of the city or locality
state_province:
type: string
minLength: 1
example: Manitoba
description: >
The state or province. For some countries (including the U.S.) only
abbreviations are allowed. Other countries allow the full name or
abbreviation.
postal_code:
allOf:
- $ref: '#/components/schemas/postal_code'
country_code:
allOf:
- $ref: '#/components/schemas/country_code'
description: >
The two-letter [ISO 3166-1 country
code](https://en.wikipedia.org/wiki/ISO_3166-1)
customs_item:
title: customs_item
type: object
description: The customs declaration for a single item in the shipment.
required:
- customs_item_id
additionalProperties: false
properties:
customs_item_id:
readOnly: true
allOf:
- $ref: '#/components/schemas/se_id'
description: A string that uniquely identifies the customs item
description:
type: string
nullable: true
maxLength: 100
default: null
description: A description of the item
quantity:
type: integer
format: int32
minimum: 0
default: 0
description: The quantity of this item in the shipment.
value:
type: number
format: double
minimum: 0
description: 'The monetary amount, in the specified currency.'
value_currency:
type: string
description: >
The currencies that are supported by ShipEngine are the ones that
specified by ISO 4217:
https://www.iso.org/iso-4217-currency-codes.html
weight:
allOf:
- $ref: '#/components/schemas/weight'
description: The item weight
harmonized_tariff_code:
type: string
nullable: true
default: null
example: 3926.1
description: >-
The [Harmonized Tariff
Code](https://en.wikipedia.org/wiki/Harmonized_System) of this item.
country_of_origin:
nullable: true
default: null
allOf:
- $ref: '#/components/schemas/country_code'
description: >
The two-letter [ISO 3166-1 country
code](https://en.wikipedia.org/wiki/ISO_3166-1) where this item
originated
unit_of_measure:
type: string
nullable: true
sku:
type: string
description: The SKU (Stock Keeping Unit) of the customs item
nullable: true
sku_description:
type: string
description: Description of the Custom Item's SKU
nullable: true
weight:
title: weight
type: object
description: The weight of a package
required:
- value
- unit
additionalProperties: false
properties:
value:
type: number
format: double
minimum: 0
exclusiveMinimum: true
description: 'The weight, in the specified unit'
unit:
allOf:
- $ref: '#/components/schemas/weight_unit'
weight_unit:
title: weight_unit
type: string
enum:
- pound
- ounce
- gram
- kilogram
description: The possible weight unit values
advanced_shipment_options:
title: advanced_shipment_options
type: object
description: Advanced shipment options
additionalProperties: false
properties:
bill_to_account:
type: string
nullable: true
default: null
description: >
This field is used to [bill shipping costs to a third
party](https://www.shipengine.com/docs/shipping/bill-to-third-party/).
This field must be used in conjunction with the
`bill_to_country_code`, `bill_to_party`, and `bill_to_postal_code`
fields.
bill_to_country_code:
nullable: true
default: null
allOf:
- $ref: '#/components/schemas/country_code'
description: >
The two-letter [ISO 3166-1 country
code](https://en.wikipedia.org/wiki/ISO_3166-1) of the third-party
that is responsible for shipping costs.
bill_to_party:
nullable: true
default: null
allOf:
- $ref: '#/components/schemas/bill_to_party'
description: >
Indicates whether to bill shipping costs to the recipient or to a
third-party. When billing to a third-party, the `bill_to_account`,
`bill_to_country_code`, and `bill_to_postal_code` fields must also
be set.
bill_to_postal_code:
type: string
nullable: true
default: null
description: >
The postal code of the third-party that is responsible for shipping
costs.
contains_alcohol:
type: boolean
default: false
description: Indicates that the shipment contains alcohol.
delivered_duty_paid:
type: boolean
default: false
description: >
Indicates that the shipper is paying the international delivery
duties for this shipment. This option is supported by UPS, FedEx,
and DHL Express.
dry_ice:
type: boolean
default: false
description: Indicates if the shipment contain dry ice
dry_ice_weight:
nullable: true
allOf:
- $ref: '#/components/schemas/weight'
description: The weight of the dry ice in the shipment
non_machinable:
type: boolean
default: false
description: >
Indicates that the package cannot be processed automatically because
it is too large or irregularly shaped. This is primarily for USPS
shipments. See [Section 1.2 of the USPS parcel
standards](https://pe.usps.com/text/dmm300/101.htm#ep1047495) for
details.
saturday_delivery:
type: boolean
default: false
description: 'Enables Saturday delivery, if supported by the carrier.'
fedex_freight:
type: object
description: Provide details for the Fedex freight service
properties:
shipper_load_and_count:
type: string
booking_confirmation:
type: string
use_ups_ground_freight_pricing:
type: boolean
nullable: true
default: null
description: >
Whether to use [UPS Ground Freight
pricing](https://www.shipengine.com/docs/shipping/ups-ground-freight/).
If enabled, then a `freight_class` must also be specified.
freight_class:
type: string
nullable: true
default: null
example: 77.5
description: >
The National Motor Freight Traffic Association [freight
class](http://www.nmfta.org/pages/nmfc?AspxAutoDetectCookieSupport=1),
such as "77.5", "110", or "250".
custom_field1:
type: string
nullable: true
default: null
maxLength: 100
description: >
An arbitrary field that can be used to store information about the
shipment.
custom_field2:
type: string
nullable: true
default: null
maxLength: 100
description: >
An arbitrary field that can be used to store information about the
shipment.
custom_field3:
type: string
nullable: true
default: null
maxLength: 100
description: >
An arbitrary field that can be used to store information about the
shipment.
origin_type:
nullable: true
default: null
allOf:
- $ref: '#/components/schemas/origin_type'
additional_handling:
type: boolean
nullable: true
default: null
description: >
Indicate to the carrier that this shipment requires additional
handling.
shipper_release:
type: boolean
nullable: true
default: null
collect_on_delivery:
$ref: '#/components/schemas/collect_on_delivery'
third_party_consignee:
type: boolean
default: false
description: >-
Third Party Consignee option is a value-added service that allows
the shipper to supply goods without commercial invoices being
attached
dangerous_goods:
type: boolean
default: false
description: Indicates if the Dangerous goods are present in the shipment
dangerous_goods_contact:
type: object
description: Contact information for Dangerous goods
properties:
name:
type: string
description: Name of the contact
phone:
type: string
description: Phone number of the contact
bill_to_party:
title: bill_to_party
type: string
enum:
- recipient
- third_party
description: The possible bill to party values
origin_type:
title: origin_type
type: string
enum:
- pickup
- drop_off
description: Indicates if the package will be picked up or dropped off by the carrier
collect_on_delivery:
title: collect_on_delivery
type: object
description: 'Defer payment until package is delivered, instead of when it is ordered.'
properties:
payment_type:
allOf:
- $ref: '#/components/schemas/collect_on_delivery_payment_type'
payment_amount:
$ref: '#/components/schemas/payment_amount'
collect_on_delivery_payment_type:
title: collect_on_delivery_payment_type
type: string
enum:
- any
- cash
- cash_equivalent
- none
description: Types of payment that are supported
payment_amount:
title: payment_amount
type: object
properties:
currency:
allOf:
- $ref: '#/components/schemas/currency'
amount:
minimum: 0
format: double
type: number
insurance_provider:
title: insurance_provider
type: string
enum:
- none
- shipsurance
- carrier
- third_party
description: The possible insurance provider values
tag:
title: tag
type: object
description: >
Tags are arbitrary strings that you can use to categorize shipments.
For example, you may want to use tags to distinguish between domestic
and international shipments, or between insured and uninsured
shipments. Or maybe you want to create a tag for each of your customers
so you can easily retrieve every shipment for a customer.
required:
- name
additionalProperties: false
properties:
name:
type: string
minLength: 1
example: Fragile
description: The tag name.
package:
title: package
type: object
description: >
A package associated with a [shipping
label](https://www.shipengine.com/docs/labels/create-a-label/)
required:
- weight
additionalProperties: false
properties:
package_id:
allOf:
- $ref: '#/components/schemas/se_id'
description: >-
A string that uniquely identifies this [package
type](https://www.shipengine.com/docs/reference/list-carrier-packages/)
package_code:
allOf:
- $ref: '#/components/schemas/package_code'
description: >
The [package
type](https://www.shipengine.com/docs/reference/list-carrier-packages/),
such as `thick_envelope`, `small_flat_rate_box`, `large_package`,
etc. The code `package` indicates a custom or unknown package type.
content_description:
type: string
minLength: 1
maxLength: 35
description: >
A short description of the package content. Required for shipments
moving to, from, and through Mexico.
example: Hand knitted wool socks
nullable: true
weight:
allOf:
- $ref: '#/components/schemas/weight'
description: The package weight
dimensions:
allOf:
- $ref: '#/components/schemas/dimensions'
description: The package dimensions
insured_value:
allOf:
- $ref: '#/components/schemas/monetary_value'
default:
- currency: usd
amount: 0
description: >
The insured value of the package. Requires the `insurance_provider`
field of the shipment to be set.
tracking_number:
readOnly: true
allOf:
- $ref: '#/components/schemas/tracking_number'
description: >
The tracking number for the package. The format depends on the
carrier.
label_messages:
allOf:
- $ref: '#/components/schemas/label_messages'
external_package_id:
type: string
minLength: 1
description: An external package id.
label_download:
readOnly: true
allOf:
- $ref: '#/components/schemas/label_download'
description: The label download for the package
form_download:
readOnly: true
allOf:
- $ref: '#/components/schemas/optional_link'
description: The form download for any customs that are needed
paperless_download:
readOnly: true
allOf:
- $ref: '#/components/schemas/paperless_download'
description: >-
The paperless details which may contain elements like `href`,
`instructions` and `handoff_code`.
sequence:
readOnly: true
format: int32
type: integer
description: Package sequence
products:
type: array
default: []
minItems: 0
description: >-
Details about products inside packages (Information provided would
be used on custom documentation)
items:
$ref: '#/components/schemas/products'
tracking_number:
title: tracking_number
type: string
minLength: 1
example: 1Z932R800392060079
description: A tracking number for a package. The format depends on the carrier.
label_messages:
title: label_messages
type: object
description: >
Custom messages to print on the shipping label for the package. These
are typically used to print invoice numbers, product numbers, or other
internal reference numbers. Not all carriers support label messages.
The number of lines and the maximum length of each line also varies by
carrier.
|Carrier |Max lines |Max line length
|-------------------|----------|--------------------
|USPS (Stamps.com) |3 |60
|FedEx |3 |35 for the first line. 30 for additional
lines.
|UPS |2 |35
|OnTrac |2 |25
required:
- reference1
- reference2
- reference3
additionalProperties: false
properties:
reference1:
type: string
nullable: true
default: null
description: >
The first line of the custom label message. Some carriers may
prefix this line with something like "REF", "Reference", "Trx Ref
No.", etc.
reference2:
type: string
nullable: true
default: null
description: >
The second line of the custom label message. Some carriers may
prefix this line with something like "INV", "Reference 2", "Trx Ref
No.", etc.
reference3:
type: string
nullable: true
default: null
description: >
The third line of the custom label message. Some carriers may
prefix this line with something like "PO", "Reference 3", etc.
products:
title: products
type: object
description: The customs declaration for a single item in the shipment.
additionalProperties: false
properties:
description:
type: string
nullable: true
maxLength: 100
default: null
description: A description of the item
quantity:
type: integer
format: int32
minimum: 0
default: 0
description: The quantity of this item in the shipment.
value:
allOf:
- $ref: '#/components/schemas/monetary_value'
description: The declared value of each item
weight:
allOf:
- $ref: '#/components/schemas/weight'
description: The item weight
harmonized_tariff_code:
type: string
nullable: true
default: null
example: 3926.1
description: >-
The [Harmonized Tariff
Code](https://en.wikipedia.org/wiki/Harmonized_System) of this item.
country_of_origin:
nullable: true
default: null
allOf:
- $ref: '#/components/schemas/country_code'
description: >
The two-letter [ISO 3166-1 country
code](https://en.wikipedia.org/wiki/ISO_3166-1) where this item
originated
unit_of_measure:
type: string
nullable: true
sku:
type: string
description: The SKU (Stock Keeping Unit) of the item
nullable: true
sku_description:
type: string
description: Description of the Custom Item's SKU
nullable: true
mid_code:
type: string
description: Manufacturers Identification code
nullable: true
product_url:
type: string
description: link to the item on the seller website
nullable: true
vat_rate:
type: number
format: double
description: VAT rate applicable to the item
nullable: true
example: 0.2
dangerous_goods:
type: array
default: []
minItems: 0
description: Details about dangerous goods inside products
items:
$ref: '#/components/schemas/dangerous_goods'
dangerous_goods:
title: dangerous_goods
type: object
description: |
Dangerous goods attribute associated with the product
additionalProperties: false
properties:
id_number:
type: string
nullable: true
default: null
description: UN number to identify the dangerous goods.
shipping_name:
type: string
nullable: true
default: null
description: Trade description of the dangerous goods.
technical_name:
type: string
nullable: true
default: null
description: Recognized Technical or chemical name of dangerous goods.
product_class:
type: string
nullable: true
default: null
description: Dangerous goods product class based on regulation.
product_class_subsidiary:
type: string
nullable: true
default: null
description: >-
A secondary of product class for substances presenting more than one
particular hazard
packaging_group:
$ref: '#/components/schemas/packaging_group'
dangerous_amount:
allOf:
- $ref: '#/components/schemas/dangerous_amount'
description: This model represents the amount of the dangerous goods.
quantity:
type: integer
format: int32
minimum: 0
default: 0
description: Quantity of dangerous goods.
packaging_instruction:
type: string
nullable: true
default: null
description: >-
The specific standardized packaging instructions from the relevant
regulatory agency that have been applied to the parcel/container.
packaging_instruction_section:
$ref: '#/components/schemas/packaging_instruction_section'
packaging_type:
type: string
nullable: true
default: null
description: The type of exterior packaging used to contain the dangerous good.
transport_mean:
$ref: '#/components/schemas/transport_mean'
transport_category:
type: string
nullable: true
default: null
description: >-
Transport category assign to dangerous goods for the transport
purpose.
regulation_authority:
type: string
nullable: true
default: null
description: Name of the regulatory authority.
regulation_level:
$ref: '#/components/schemas/regulation_level'
radioactive:
type: boolean
nullable: true
example: false
description: Indication if the substance is radioactive.
reportable_quantity:
type: boolean
nullable: true
example: false
description: >-
Indication if the substance needs to be reported to regulatory
authority based on the quantity.
tunnel_code:
type: string
nullable: true
default: null
description: Defines which types of tunnels the shipment is allowed to go through
additional_description:
type: string
nullable: true
default: null
description: >-
Provider additonal description regarding the dangerous goods. This
is used as a placed holder to provider additional context and varies
by carrier
packaging_group:
title: packaging_group
type: string
enum:
- i
- ii
- iii
dangerous_amount:
title: dangerous_amount
type: object
description: This model represents the amount of the dangerous goods..
additionalProperties: false
properties:
amount:
type: integer
format: int32
minimum: 0
default: 0
description: The amount of dangerous goods.
unit:
type: string
nullable: true
default: null
description: The unit of dangerous goods.
packaging_instruction_section:
title: packaging_instruction_section
type: string
enum:
- section_1
- section_2
- section_1a
- section_1b
transport_mean:
title: transport_mean
type: string
enum:
- ground
- water
- cargo_aircraft_only
- passenger_aircraft
regulation_level:
title: regulation_level
type: string
enum:
- lightly_regulated
- fully_regulated
- limited_quantities
- excepted_quantity
label_charge_event:
title: label_charge_event
type: string
enum:
- carrier_default
- on_creation
- on_carrier_acceptance
description: Determines when the user's account will be charged for the label.
validate_address:
title: validate_address
type: string
enum:
- no_validation
- validate_only
- validate_and_clean
description: The possible validate address values
label_download_type:
title: label_download_type
type: string
enum:
- url
- inline
description: >
There are two different ways to [download a
label](https://www.shipengine.com/docs/labels/downloading/):
|Label Download Type | Description
|--------------------|------------------------------
|`url` |You will receive a URL, which you can use to
download the label in a separate request. The URL will remain valid for
90 days.
This is the default if `label_download_type` is
unspecified.
|`inline` |You will receive the Base64-encoded label as part
of the response. No need for a second request to download the label.
tracking_status:
title: tracking_status
type: string
enum:
- unknown
- in_transit
- error
- delivered
description: The different statuses that can apply to a shipment.
alternative_identifiers:
title: alternative_identifiers
type: object
additionalProperties: false
properties:
alternative_identifiers:
type: array
readOnly: true
nullable: true
description: |
Alternative identifiers associated with this package.
items:
$ref: '#/components/schemas/alternative_identifier'
alternative_identifier:
title: alternative_identifier
type: object
description: >
Additional information some carriers may provide by which to identify a
given label in their system.
additionalProperties: false
properties:
type:
type: string
minLength: 1
example: last_mile_tracking_number
description: |
The type of alternative_identifier that corresponds to the value.
value:
type: string
minLength: 1
example: '12345678912345678912'
description: |
The value of the alternative_identifier.
create_label_response_body:
title: create_label_response_body
type: object
description: A create label response body
additionalProperties: false
required:
- label_id
- status
- shipment_id
- ship_date
- created_at
- shipment_cost
- insurance_cost
- tracking_number
- is_international
- batch_id
- carrier_id
- service_code
- voided
- voided_at
- label_image_id
- label_format
- label_layout
- trackable
- carrier_code
- tracking_status
- label_download
- form_download
- paperless_download
- insurance_claim
- packages
- is_return_label
- rma_number
- charge_event
- package_code
- display_scheme
allOf:
- $ref: '#/components/schemas/label'
get_label_by_external_shipment_id_response_body:
title: get_label_by_external_shipment_id_response_body
type: object
description: A get label by external shipment id response body
additionalProperties: false
allOf:
- $ref: '#/components/schemas/label'
create_label_from_rate_request_body:
title: create_label_from_rate_request_body
type: object
description: A purchase label without shipment request body
additionalProperties: false
allOf:
- $ref: '#/components/schemas/purchase_label_without_shipment'
purchase_label_without_shipment:
title: purchase_label_without_shipment
type: object
description: A purchase label without shipment resource
additionalProperties: false
properties:
validate_address:
allOf:
- $ref: '#/components/schemas/validate_address'
label_layout:
default: 4x6
allOf:
- $ref: '#/components/schemas/label_layout'
label_format:
default: pdf
allOf:
- $ref: '#/components/schemas/label_format'
label_download_type:
allOf:
- $ref: '#/components/schemas/label_download_type'
display_scheme:
default: label
allOf:
- $ref: '#/components/schemas/display_scheme'
description: The display format that the label should be shown in.
create_label_from_rate_response_body:
title: create_label_from_rate_response_body
type: object
description: A create label from rate response body
additionalProperties: false
allOf:
- $ref: '#/components/schemas/label'
create_label_from_shipment_request_body:
title: create_label_from_shipment_request_body
type: object
description: A purchase label without shipment request body
additionalProperties: false
properties:
validate_address:
allOf:
- $ref: '#/components/schemas/validate_address'
label_layout:
default: 4x6
allOf:
- $ref: '#/components/schemas/label_layout'
label_format:
default: pdf
allOf:
- $ref: '#/components/schemas/label_format'
label_download_type:
allOf:
- $ref: '#/components/schemas/label_download_type'
display_scheme:
default: label
allOf:
- $ref: '#/components/schemas/display_scheme'
description: The display format that the label should be shown in.
create_label_from_shipment_response_body:
title: create_label_from_shipment_response_body
type: object
description: A create label from shipment response body
additionalProperties: false
allOf:
- $ref: '#/components/schemas/label'
get_label_by_id_response_body:
title: get_label_by_id_response_body
type: object
description: A get label by id response body
additionalProperties: false
allOf:
- $ref: '#/components/schemas/label'
create_return_label_request_body:
title: create_return_label_request_body
type: object
description: A create return label request body
additionalProperties: false
properties:
charge_event:
allOf:
- $ref: '#/components/schemas/label_charge_event'
description: |
The label charge event.
label_layout:
default: 4x6
allOf:
- $ref: '#/components/schemas/label_layout'
description: >
The layout (size) that you want the label to be in. The
`label_format` determines which sizes are allowed. `4x6` is
supported for all label formats, whereas `letter` (8.5" x 11") is
only supported for `pdf` format.
label_format:
default: pdf
allOf:
- $ref: '#/components/schemas/label_format'
description: >
The file format that you want the label to be in. We recommend
`pdf` format because it is supported by all carriers, whereas some
carriers do not support the `png` or `zpl` formats.
label_download_type:
writeOnly: true
default: url
allOf:
- $ref: '#/components/schemas/label_download_type'
display_scheme:
default: label
allOf:
- $ref: '#/components/schemas/display_scheme'
description: The display format that the label should be shown in.
label_image_id:
nullable: true
allOf:
- $ref: '#/components/schemas/image_id'
description: >-
The label image resource that was used to create a custom label
image.
create_return_label_response_body:
title: create_return_label_response_body
type: object
description: A create return label response body
additionalProperties: false
allOf:
- $ref: '#/components/schemas/label'
get_tracking_log_from_label_response_body:
title: get_tracking_log_from_label_response_body
type: object
description: A get tracking log from label response body
required:
- tracking_number
- status_code
- carrier_status_code
- estimated_delivery_date
- events
additionalProperties: false
allOf:
- $ref: '#/components/schemas/tracking_information'
tracking_information:
title: tracking_information
type: object
description: A tracking information resource
additionalProperties: false
properties:
tracking_number:
allOf:
- $ref: '#/components/schemas/tracking_number'
tracking_url:
type: string
readOnly: true
example: 'https://www.fedex.com/fedextrack/?action=track&trackingnumber=1234'
description: 'Carrier Tracking Url, if available'
status_code:
allOf:
- $ref: '#/components/schemas/status_code'
carrier_code:
allOf:
- $ref: '#/components/schemas/carrier_code'
carrier_id:
allOf:
- $ref: '#/components/schemas/se_id'
status_description:
type: string
readOnly: true
example: Delivered
minLength: 0
description: Status description
carrier_status_code:
type: string
readOnly: true
minLength: 1
example: 1
description: Carrier status code
carrier_detail_code:
type: string
readOnly: true
minLength: 1
example: OT
description: Carrier detail code
carrier_status_description:
type: string
minLength: 0
readOnly: true
example: 'Your item was delivered in or at the mailbox at 9:10 am on March'
description: carrier status description
ship_date:
allOf:
- $ref: '#/components/schemas/date_time'
estimated_delivery_date:
allOf:
- $ref: '#/components/schemas/date_time'
actual_delivery_date:
allOf:
- $ref: '#/components/schemas/date_time'
exception_description:
type: string
readOnly: true
minLength: 0
description: Exception description
events:
type: array
readOnly: true
items:
$ref: '#/components/schemas/track_event'
description: >-
The events that have occured during the lifetime of this tracking
number.
status_code:
readOnly: true
title: status_code
enum:
- un
- ac
- it
- de
- ex
- at
- ny
type: string
description: |
The tracking status codes
|Value |Description
|:--------- |:-----------------------------------------------------
|`un` | Unknown
|`ac` | Accepted
|`it` | In Transit
|`de` | Delivered
|`ex` | Exception
|`at` | Delivery Attempt
|`ny` | Not Yet In System
track_event:
title: track_event
type: object
description: A track event
required:
- occurred_at
- city_locality
- state_province
- postal_code
- carrier_detail_code
- status_code
- status_description
- carrier_status_code
- carrier_status_description
additionalProperties: false
properties:
occurred_at:
allOf:
- $ref: '#/components/schemas/date_time'
description: Timestamp for carrier event
carrier_occurred_at:
allOf:
- $ref: '#/components/schemas/date_time'
description: >-
Carrier timestamp for the event, it is assumed to be the local time
of where the event occurred.
description:
type: string
readOnly: true
minLength: 0
example: 'Delivered, In/At Mailbox'
description: Event description
city_locality:
type: string
readOnly: true
example: AUSTIN
minLength: 0
description: City locality
state_province:
type: string
readOnly: true
example: TX
minLength: 2
description: State province
postal_code:
type: string
readOnly: true
example: 78756
minLength: 0
description: Postal code
country_code:
allOf:
- $ref: '#/components/schemas/country_code'
company_name:
type: string
readOnly: true
example: Stamps.com
minLength: 0
description: Company Name
signer:
type: string
minLength: 0
readOnly: true
description: Signer information
event_code:
type: string
minLength: 0
description: Event Code
carrier_detail_code:
type: string
readOnly: true
minLength: 1
example: OT
description: Carrier detail code
status_code:
allOf:
- $ref: '#/components/schemas/status_code'
status_description:
type: string
readOnly: true
minLength: 1
example: In Transit
description: Event Status Description
carrier_status_code:
type: string
readOnly: true
minLength: 1
example: 1
description: Carrier status code
carrier_status_description:
type: string
minLength: 0
readOnly: true
example: 'Your item was delivered in or at the mailbox at 9:10 am on March'
description: carrier status description
latitude:
type: number
format: double
minimum: -90
maximum: 90
description: Latitude coordinate of tracking event.
longitude:
type: number
format: double
minimum: -180
maximum: 180
description: Longitude coordinate of tracking event.
void_label_response_body:
title: void_label_response_body
type: object
description: A void label response body
required:
- approved
- message
additionalProperties: false
properties:
approved:
type: boolean
readOnly: true
example: false
description: Indicates whether the attempt to void the label was successful
message:
type: string
minLength: 0
readOnly: true
example: >-
Unable to delete FedEx shipment. Unable to retrieve record from
database.
reason_code:
readOnly: true
type: string
allOf:
- $ref: '#/components/schemas/reason_code'
description: >-
Indicates a normalized reason for the conditions if the void attempt
was not approved. Will not populate if approved is true. “unknown”
codes may be specified later.
example: label_not_found_within_void_period
reason_code:
title: reason_code
type: string
enum:
- unknown
- unspecified
- validation_failed
- label_not_found_within_void_period
- label_already_used
- label_already_voided
- contact_carrier
description: >-
The possible normalized reasons a label void request may not have been
approved
list_manifests_response_body:
title: list_manifests_response_body
type: object
description: A list manifests response body
required:
- manifests
- total
- page
- pages
- links
additionalProperties: false
properties:
manifests:
type: array
readOnly: true
default: []
items:
readOnly: true
allOf:
- $ref: '#/components/schemas/manifest'
description: A single manifest
description: The list of available manifests
total:
type: integer
format: int64
readOnly: true
minimum: 0
example: 3
description: The total number of manifests returned
page:
type: integer
format: int32
readOnly: true
minimum: 1
example: 3
description: Current page of the list manifests results
pages:
type: integer
format: int32
readOnly: true
minimum: 1
example: 4
description: Total number of pages for list manifests results
links:
readOnly: true
allOf:
- $ref: '#/components/schemas/pagination_link'
description: Helpful links to other pages of results
manifest:
title: manifest
type: object
description: >
Used for combining packages into one scannable form that a carrier can
use when picking up a large
number of shipments
additionalProperties: false
properties:
manifest_id:
readOnly: true
allOf:
- $ref: '#/components/schemas/se_id'
description: A string that uniquely identifies the manifest
form_id:
readOnly: true
allOf:
- $ref: '#/components/schemas/se_id'
description: A string that uniquely identifies the form
created_at:
type: string
format: date-time
minLength: 1
readOnly: true
example: '2019-07-12T13:37:39.050Z'
description: The date-time that the manifest was created
ship_date:
type: string
format: date-time
minLength: 1
readOnly: true
example: '2019-07-12T13:37:39.050Z'
description: The date-time that the manifests shipments will be picked up
shipments:
type: integer
format: int32
readOnly: true
minimum: 1
example: 100
description: The number of shipments that are included in this manifest
label_ids:
type: array
readOnly: true
items:
allOf:
- $ref: '#/components/schemas/se_id'
description: An array of the label ids used in this manifest.
warehouse_id:
readOnly: true
allOf:
- $ref: '#/components/schemas/se_id'
description: A string that uniquely identifies the warehouse
submission_id:
readOnly: true
type: string
minLength: 1
example: '9475711899564878915476'
description: A string that uniquely identifies the submission
carrier_id:
readOnly: true
allOf:
- $ref: '#/components/schemas/se_id'
description: A string that uniquely identifies the carrier
manifest_download:
readOnly: true
allOf:
- $ref: '#/components/schemas/manifest_download'
manifest_download:
title: manifest_download
type: object
description: Object containing the href link to download the manifest file
additionalProperties: false
properties:
href:
allOf:
- $ref: '#/components/schemas/url'
description: 'The URL of the linked resource, if any'
create_manifest_request_body:
title: create_manifest_request_body
oneOf:
- $ref: '#/components/schemas/create_manifest_by_object_request_body'
- $ref: '#/components/schemas/create_manifest_label_ids_request_body'
create_manifest_by_object_request_body:
title: create_manifest_by_object_request_body
type: object
description: A create manifest request body
required:
- carrier_id
- warehouse_id
- ship_date
additionalProperties: false
properties:
carrier_id:
allOf:
- $ref: '#/components/schemas/se_id'
description: A string that uniquely identifies the carrier
excluded_label_ids:
type: array
items:
allOf:
- $ref: '#/components/schemas/se_id'
description: Label Id that will be excluded from the manifest
description: The list of label ids to exclude from the manifest
label_ids:
type: array
items:
allOf:
- $ref: '#/components/schemas/se_id'
description: Label Id that will be included for the manifest
description: The list of label ids to include for the manifest
warehouse_id:
allOf:
- $ref: '#/components/schemas/se_id'
description: A string that uniquely identifies the warehouse
ship_date:
type: string
format: date-time
minLength: 1
example: '2018-09-23T15:00:00.000Z'
description: The ship date that the shipment will be sent out on
create_manifest_label_ids_request_body:
title: create_manifest_label_ids_request_body
type: object
description: A create manifest request body
required:
- label_ids
additionalProperties: false
properties:
label_ids:
type: array
items:
allOf:
- $ref: '#/components/schemas/se_id'
description: Label Id that will be included in the manifest
description: The list of label ids to include in the manifest
create_manifest_response_body:
title: create_manifest_response_body
type: object
description: A create manifest response body
required:
- manifest_id
- form_id
- created_at
- ship_date
- shipments
- warehouse_id
- submission_id
- carrier_id
- manifest_download
additionalProperties: false
allOf:
- $ref: '#/components/schemas/manifests'
- $ref: '#/components/schemas/manifests_requests'
- $ref: '#/components/schemas/deprecated_manifest'
- $ref: '#/components/schemas/error_with_label_id_response_body'
manifests:
title: manifests
type: object
description: An array of manifest resources
additionalProperties: false
properties:
manifests:
description: Resulting Manifests
type: array
items:
$ref: '#/components/schemas/manifest'
manifests_requests:
title: manifests_requests
type: object
description: An array of manifest requests
additionalProperties: false
properties:
manifest_requests:
description: Resulting manifest requests with statuses
type: array
items:
$ref: '#/components/schemas/manifest_request'
manifest_request:
title: manifest_request
type: object
description: A reference to the manifest request
additionalProperties: false
properties:
manifest_request_id:
readOnly: true
allOf:
- $ref: '#/components/schemas/se_id'
description: A string that uniquely identifies a manifest request
status:
allOf:
- $ref: '#/components/schemas/manifest_request_status'
manifest_request_status:
title: manifest_request_status
type: string
enum:
- in_progress
- completed
description: The possible statuses of a manifest request
deprecated_manifest:
title: deprecated_manifest
type: object
description: Deprecated manifest resource
additionalProperties: false
properties:
manifest_id:
deprecated: true
allOf:
- $ref: '#/components/schemas/se_id'
description: A string that uniquely identifies the manifest
form_id:
deprecated: true
allOf:
- $ref: '#/components/schemas/se_id'
description: A string that uniquely identifies the form
created_at:
deprecated: true
type: string
format: date-time
minLength: 1
example: '2019-07-12T13:37:39.050Z'
description: The date-time that the manifest was created
ship_date:
deprecated: true
type: string
format: date-time
minLength: 1
example: '2019-07-12T13:37:39.050Z'
description: The date-time that the manifests shipments will be picked up
shipments:
deprecated: true
type: integer
format: int32
readOnly: true
minimum: 1
example: 100
description: The number of shipments that are included in this manifest
warehouse_id:
deprecated: true
allOf:
- $ref: '#/components/schemas/se_id'
description: A string that uniquely identifies the warehouse
submission_id:
deprecated: true
type: string
minLength: 1
example: '9475711899564878915476'
description: A string that uniquely identifies the submission
carrier_id:
deprecated: true
allOf:
- $ref: '#/components/schemas/se_id'
description: A string that uniquely identifies the carrier
manifest_download:
deprecated: true
allOf:
- $ref: '#/components/schemas/manifest_download'
label_ids:
deprecated: true
type: array
readOnly: true
items:
allOf:
- $ref: '#/components/schemas/se_id'
description: An array of the label ids used in this manifest.
error_with_label_id_response_body:
title: error_with_label_id_response_body
type: object
description: An error response body
required:
- request_id
- errors
additionalProperties: false
properties:
request_id:
allOf:
- $ref: '#/components/schemas/uuid'
description: >
A UUID that uniquely identifies the request id.
This can be given to the support team to help debug non-trivial
issues that may occur
errors:
type: array
readOnly: true
items:
allOf:
- $ref: '#/components/schemas/error'
description: The errors associated with the failed API call
get_manifest_by_id_response_body:
title: get_manifest_by_id_response_body
type: object
description: A get manifest by id response body
required:
- manifest_id
- form_id
- created_at
- ship_date
- shipments
- warehouse_id
- submission_id
- carrier_id
- manifest_download
- label_ids
additionalProperties: false
allOf:
- $ref: '#/components/schemas/manifest'
list_package_types_response_body:
title: list_package_types_response_body
type: object
description: A list package types response body
additionalProperties: false
properties:
packages:
type: array
readOnly: true
items:
readOnly: true
allOf:
- $ref: '#/components/schemas/package_type'
description: Custom Package Types items
description: An array of custom package types
create_package_type_request_body:
title: create_package_type_request_body
type: object
description: A create package type request body
additionalProperties: false
allOf:
- $ref: '#/components/schemas/package_type'
create_package_type_response_body:
title: create_package_type_response_body
type: object
description: A create package type response body
additionalProperties: false
allOf:
- $ref: '#/components/schemas/package_type'
get_package_type_by_id_response_body:
title: get_package_type_by_id_response_body
type: object
description: A get package type by id response body
additionalProperties: false
allOf:
- $ref: '#/components/schemas/package_type'
update_package_type_request_body:
title: update_package_type_request_body
type: object
description: An update package type request body
additionalProperties: false
allOf:
- $ref: '#/components/schemas/package_type'
get_pickups_response_body:
title: get_pickups_response_body
allOf:
- $ref: '#/components/schemas/list_pickup_response_body'
- $ref: '#/components/schemas/error_response_body'
list_pickup_response_body:
title: list_pickup_response_body
type: object
description: A list pickup response body
required:
- pickups
- total
- page
- pages
- links
additionalProperties: false
properties:
pickups:
type: array
description: An array of pickups associated with the user's account.
items:
allOf:
- $ref: '#/components/schemas/pickup'
total:
type: integer
format: int64
readOnly: true
minimum: 0
example: 3
description: The total number of pickups returned
page:
type: integer
format: int32
readOnly: true
minimum: 1
example: 3
description: Current page of the list pickups results
pages:
type: integer
format: int32
readOnly: true
minimum: 1
example: 4
description: Total number of pages for list pickups results
links:
readOnly: true
allOf:
- $ref: '#/components/schemas/pagination_link'
description: Helpful links to other pages of results
pickup:
title: pickup
type: object
description: |
The information necessary to schedule a package pickup
additionalProperties: false
properties:
pickup_id:
readOnly: true
allOf:
- $ref: '#/components/schemas/pickup_resource_id'
label_ids:
type: array
items:
allOf:
- $ref: '#/components/schemas/se_id'
description: Label ID that will be included in the pickup request
description: Label IDs that will be included in the pickup request
created_at:
readOnly: true
allOf:
- $ref: '#/components/schemas/date_time'
description: The date and time that the pickup was created in ShipEngine.
cancelled_at:
readOnly: true
allOf:
- $ref: '#/components/schemas/date_time'
description: The date and time that the pickup was cancelled in ShipEngine.
carrier_id:
readOnly: true
allOf:
- $ref: '#/components/schemas/se_id'
description: The carrier_id associated with the pickup
confirmation_number:
readOnly: true
type: string
nullable: true
description: The carrier confirmation number for the scheduled pickup.
example: 292513CL4A3
warehouse_id:
readOnly: true
allOf:
- $ref: '#/components/schemas/se_id'
description: The warehouse_id associated with the pickup
pickup_address:
readOnly: true
allOf:
- $ref: '#/components/schemas/address'
contact_details:
$ref: '#/components/schemas/contact_details'
pickup_notes:
type: string
minLength: 0
description: >-
Used by some carriers to give special instructions for a package
pickup
pickup_window:
$ref: '#/components/schemas/pickup_window'
pickup_windows:
readOnly: true
type: array
description: >
An array of available pickup windows. Carriers can return multiple
times that they will pickup packages.
items:
allOf:
- $ref: '#/components/schemas/pickup_windows'
pickup_resource_id:
title: pickup_resource_id
type: string
minLength: 4
example: pik_3YcKU5zdtJuCqoeNwyqqbW
description: Pickup Resource ID
contact_details:
title: contact_details
type: object
required:
- name
- email
- phone
properties:
name:
type: string
minLength: 1
email:
allOf:
- $ref: '#/components/schemas/email'
phone:
type: string
minLength: 7
description: Phone number associated
pickup_window:
title: pickup_window
writeOnly: true
type: object
description: The desired time range for the package pickup.
required:
- start_at
- end_at
properties:
start_at:
allOf:
- $ref: '#/components/schemas/date_time'
end_at:
allOf:
- $ref: '#/components/schemas/date_time'
pickup_windows:
title: pickup_windows
type: object
properties:
start_at:
allOf:
- $ref: '#/components/schemas/date_time'
end_at:
allOf:
- $ref: '#/components/schemas/date_time'
schedule_pickup_request_body:
title: schedule_pickup_request_body
type: object
description: A schedule pickup request body
required:
- contact_details
- label_ids
- pickup_window
additionalProperties: false
allOf:
- $ref: '#/components/schemas/pickup'
schedule_pickup_response_body:
title: schedule_pickup_response_body
allOf:
- $ref: '#/components/schemas/pickup'
- $ref: '#/components/schemas/error_response_body'
get_pickup_by_id_response_body:
title: get_pickup_by_id_response_body
allOf:
- $ref: '#/components/schemas/pickup_response_body'
- $ref: '#/components/schemas/error_response_body'
pickup_response_body:
title: pickup_response_body
type: object
description: A pickup response body
required:
- pickup
- pickup_id
- label_ids
- created_at
- carrier_id
- warehouse_id
- pickup_address
- contact_details
- notes
- pickup_window
- confirmation_number
additionalProperties: false
allOf:
- $ref: '#/components/schemas/pickup'
delete_pickup_by_id_response_body:
title: delete_pickup_by_id_response_body
allOf:
- $ref: '#/components/schemas/error_response_body'
- $ref: '#/components/schemas/delete_scheduled_pickup_response_body'
delete_scheduled_pickup_response_body:
title: delete_scheduled_pickup_response_body
type: object
description: A delete scheduled pickup response body
additionalProperties: false
required:
- pickup_id
properties:
pickup_id:
allOf:
- $ref: '#/components/schemas/pickup_resource_id'
calculate_rates_request_body:
title: calculate_rates_request_body
type: object
description: A rate shipment request body
required:
- shipment_id
- shipment
additionalProperties: false
oneOf:
- $ref: '#/components/schemas/shipment_id_request'
- $ref: '#/components/schemas/shipment_request'
allOf:
- $ref: '#/components/schemas/rate_request_options'
shipment_id_request:
title: shipment_id_request
type: object
properties:
shipment_id:
allOf:
- $ref: '#/components/schemas/se_id'
description: A string that uniquely identifies the shipment
shipment_request:
title: shipment_request
type: object
properties:
shipment:
allOf:
- $ref: '#/components/schemas/address_validating_shipment'
description: The shipment object
address_validating_shipment:
title: address_validating_shipment
type: object
description: An address validating shipment
required:
- shipment_id
- carrier_id
- service_code
- ship_to
- ship_from
additionalProperties: false
allOf:
- $ref: '#/components/schemas/validate_shipment_fields'
- $ref: '#/components/schemas/partial_shipment'
validate_shipment_fields:
title: validate_shipment_fields
type: object
properties:
validate_address:
default: no_validation
allOf:
- $ref: '#/components/schemas/validate_address'
rate_request_options:
title: rate_request_options
type: object
properties:
rate_options:
allOf:
- $ref: '#/components/schemas/rate_request_body'
description: The rate options
rate_request_body:
title: rate_request_body
type: object
description: A rate request body
required:
- carrier_ids
additionalProperties: false
properties:
carrier_ids:
type: array
minItems: 1
items:
allOf:
- $ref: '#/components/schemas/se_id'
description: carrier ids
description: Array of carrier ids to get rates for
package_types:
type: array
items:
type: string
minLength: 1
service_codes:
type: array
items:
type: string
minLength: 1
description: Item Service Codes
calculate_tax_amount:
type: boolean
description: Calculate the duties and tariffs for cross border shipments.
preferred_currency:
allOf:
- $ref: '#/components/schemas/currency'
is_return:
type: boolean
description: Indicate if it's a return shipment
calculate_rates_response_body:
title: calculate_rates_response_body
type: object
description: A rate shipment response body
required:
- rate_response
- shipment_id
- ship_date
- created_at
- modified_at
- shipment_status
- return_to
- confirmation
- customs
- advanced_options
- insurance_provider
- tags
- packages
- total_weight
additionalProperties: false
allOf:
- $ref: '#/components/schemas/partial_shipment'
- $ref: '#/components/schemas/rate_response'
rate_response:
title: rate_response
type: object
additionalProperties: false
properties:
rate_response:
allOf:
- $ref: '#/components/schemas/rates_information'
description: The rates response
rates_information:
title: rates_information
type: object
description: A rates information resource
additionalProperties: false
properties:
rates:
type: array
readOnly: true
items:
readOnly: true
allOf:
- $ref: '#/components/schemas/rate'
description: Shipment Rates
description: An array of shipment rates
invalid_rates:
type: array
readOnly: true
default: []
items:
readOnly: true
allOf:
- $ref: '#/components/schemas/rate'
description: Invalid Shipment Rate
description: An array of invalid shipment rates
rate_request_id:
readOnly: true
allOf:
- $ref: '#/components/schemas/se_id'
description: A string that uniquely identifies the rate request
shipment_id:
readOnly: true
allOf:
- $ref: '#/components/schemas/se_id'
description: A string that uniquely identifies the shipment
created_at:
type: string
format: date-time
allOf:
- $ref: '#/components/schemas/se_id'
description: When the rate was created
status:
readOnly: true
allOf:
- $ref: '#/components/schemas/rate_response_status'
errors:
type: array
items:
allOf:
- $ref: '#/components/schemas/error'
rate:
title: rate
type: object
description: A rate
required:
- rate_id
- rate_type
- carrier_id
- shipping_amount
- insurance_amount
- confirmation_amount
- other_amount
- zone
- package_type
- guaranteed_service
- negotiated_rate
- service_type
- service_code
- trackable
- carrier_code
- carrier_nickname
- carrier_friendly_name
- validation_status
- warning_messages
- error_messages
additionalProperties: false
properties:
rate_id:
readOnly: true
allOf:
- $ref: '#/components/schemas/se_id'
description: A string that uniquely identifies the rate
rate_type:
readOnly: true
allOf:
- $ref: '#/components/schemas/rate_type'
carrier_id:
readOnly: true
allOf:
- $ref: '#/components/schemas/se_id'
description: A string that uniquely identifies the carrier
shipping_amount:
readOnly: true
allOf:
- $ref: '#/components/schemas/monetary_value'
description: >-
The shipping amount. Should be added with confirmation_amount,
insurance_amount and other_amount to calculate the total purchase
price.
insurance_amount:
readOnly: true
allOf:
- $ref: '#/components/schemas/monetary_value'
description: >-
The insurance amount. Should be added with shipping_amount,
confirmation_amount and other_amount to calculate the total purchase
price.
confirmation_amount:
readOnly: true
allOf:
- $ref: '#/components/schemas/monetary_value'
description: >-
The confirmation amount. Should be added with shipping_amount,
insurance_amount and other_amount to calculate the total purchase
price.
other_amount:
readOnly: true
allOf:
- $ref: '#/components/schemas/monetary_value'
description: >-
Any other charges associated with this rate. Should be added with
shipping_amount, insurance_amount and confirmation_amount to
calculate the total purchase price.
requested_comparison_amount:
readOnly: true
allOf:
- $ref: '#/components/schemas/monetary_value'
description: The total shipping cost for the specified comparison_rate_type.
tax_amount:
readOnly: true
allOf:
- $ref: '#/components/schemas/monetary_value'
description: >-
Tariff and additional taxes associated with an international
shipment.
zone:
type: integer
format: int32
nullable: true
readOnly: true
minimum: 0
example: 6
description: >
Certain carriers base [their
rates](https://blog.stamps.com/2017/09/08/usps-postal-zones/) off of
custom zones that vary depending upon the ship_to and ship_from
location
package_type:
type: string
nullable: true
readOnly: true
minLength: 1
example: package
description: package type that this rate was estimated for
delivery_days:
type: integer
format: int32
readOnly: true
minimum: 1
example: 5
description: >
The number of days estimated for delivery, this will show the
_actual_ delivery
time if for example, the package gets shipped on a Friday
guaranteed_service:
type: boolean
readOnly: true
description: Indicates if the rate is guaranteed.
estimated_delivery_date:
readOnly: true
allOf:
- $ref: '#/components/schemas/date'
carrier_delivery_days:
type: string
readOnly: true
minLength: 1
description: The carrier delivery days
ship_date:
type: string
format: date-time
readOnly: true
minLength: 1
description: ship date
negotiated_rate:
type: boolean
readOnly: true
description: Indicates if the rates been negotiated
service_type:
type: string
readOnly: true
minLength: 1
description: service type
service_code:
type: string
readOnly: true
minLength: 1
description: service code for the rate
trackable:
type: boolean
readOnly: true
description: Indicates if rate is trackable
carrier_code:
type: string
readOnly: true
minLength: 1
description: carrier code
carrier_nickname:
type: string
readOnly: true
minLength: 1
description: carrier nickname
carrier_friendly_name:
type: string
readOnly: true
minLength: 1
description: carrier friendly name
validation_status:
readOnly: true
allOf:
- $ref: '#/components/schemas/validation_status'
warning_messages:
type: array
readOnly: true
minItems: 0
items:
type: string
readOnly: true
minLength: 0
description: warning message
description: The warning messages
error_messages:
type: array
readOnly: true
minItems: 0
items:
type: string
readOnly: true
minLength: 0
description: error message
description: The error messages
rate_type:
title: rate_type
type: string
enum:
- check
- shipment
description: The possible rate type values
validation_status:
title: validation_status
type: string
enum:
- valid
- invalid
- has_warnings
- unknown
description: The possible validation status values
rate_response_status:
title: rate_response_status
type: string
enum:
- working
- completed
- partial
- error
description: The possible rate response status values
compare_bulk_rates_request_body:
title: compare_bulk_rates_request_body
type: object
description: A rate shipments request body
required:
- rate_options
additionalProperties: false
allOf:
- $ref: '#/components/schemas/rate_request_rate_options'
oneOf:
- $ref: '#/components/schemas/rate_request_by_shipment_ids'
- $ref: '#/components/schemas/rate_request_by_shipments'
rate_request_rate_options:
title: rate_request_rate_options
type: object
properties:
rate_options:
allOf:
- $ref: '#/components/schemas/rate_request_body'
description: The rate options
rate_request_by_shipment_ids:
title: rate_request_by_shipment_ids
type: object
required:
- shipment_ids
properties:
shipment_ids:
type: array
items:
allOf:
- $ref: '#/components/schemas/se_id'
description: shipment ids
description: The array of shipment IDs
rate_request_by_shipments:
title: rate_request_by_shipments
type: object
required:
- shipments
properties:
shipments:
type: array
minItems: 1
items:
allOf:
- $ref: '#/components/schemas/address_validating_shipment'
description: The shipment to get a bulk rate estimate for
description: The array of shipments to get bulk rate estimates for
compare_bulk_rates_response_body:
title: compare_bulk_rates_response_body
type: array
description: A bulk rate response body
items:
$ref: '#/components/schemas/bulk_rate'
bulk_rate:
title: bulk_rate
type: object
description: A bulk rate
required:
- rate_request_id
- shipment_id
- created_at
- status
- errors
additionalProperties: false
properties:
rate_request_id:
readOnly: true
allOf:
- $ref: '#/components/schemas/se_id'
description: A string that uniquely identifies the rate request
shipment_id:
readOnly: true
allOf:
- $ref: '#/components/schemas/se_id'
description: A string that uniquely identifies the shipment
created_at:
type: string
format: date-time
readOnly: true
allOf:
- $ref: '#/components/schemas/date_time'
status:
readOnly: true
allOf:
- $ref: '#/components/schemas/rate_response_status'
errors:
type: array
readOnly: true
items:
readOnly: true
allOf:
- $ref: '#/components/schemas/error'
description: An error that occurred while retrieving the bulk rate
description: An array of errors that were returned while retrieving the bulk rate
estimate_rates_request_body:
title: estimate_rates_request_body
type: object
description: A rate estimate request body
required:
- from_country_code
- from_postal_code
- from_city_locality
- from_state_province
- to_country_code
- to_postal_code
- to_city_locality
- to_state_province
- weight
- ship_date
additionalProperties: false
oneOf:
- $ref: '#/components/schemas/rate_estimate_by_carrier_id'
- $ref: '#/components/schemas/rate_estimate_by_carrier_ids'
allOf:
- $ref: '#/components/schemas/rate_estimate_options'
rate_estimate_by_carrier_id:
title: rate_estimate_by_carrier_id
type: object
properties:
carrier_id:
deprecated: true
allOf:
- $ref: '#/components/schemas/se_id'
description: A string that uniquely identifies the carrier
rate_estimate_by_carrier_ids:
title: rate_estimate_by_carrier_ids
type: object
properties:
carrier_ids:
type: array
minItems: 1
items:
type: string
allOf:
- $ref: '#/components/schemas/se_id'
description: carrier id
description: Array of Carrier Ids
rate_estimate_options:
title: rate_estimate_options
type: object
properties:
from_country_code:
allOf:
- $ref: '#/components/schemas/country_code'
from_postal_code:
allOf:
- $ref: '#/components/schemas/postal_code'
from_city_locality:
type: string
minLength: 1
example: Austin
description: from postal code
from_state_province:
type: string
minLength: 1
example: Austin
description: From state province
to_country_code:
allOf:
- $ref: '#/components/schemas/country_code'
to_postal_code:
allOf:
- $ref: '#/components/schemas/postal_code'
to_city_locality:
type: string
minLength: 1
example: Austin
description: The city locality the package is being shipped to
to_state_province:
type: string
minLength: 1
example: Houston
description: To state province
weight:
allOf:
- $ref: '#/components/schemas/weight'
description: The weight of the package
dimensions:
allOf:
- $ref: '#/components/schemas/dimensions'
description: The dimensions of the package
confirmation:
allOf:
- $ref: '#/components/schemas/delivery_confirmation'
address_residential_indicator:
allOf:
- $ref: '#/components/schemas/address_residential_indicator'
ship_date:
type: string
allOf:
- $ref: '#/components/schemas/date_time'
description: ship date
estimate_rates_response_body:
title: estimate_rates_response_body
type: array
description: A rate estimate response body
items:
allOf:
- $ref: '#/components/schemas/rate_estimate'
rate_estimate:
title: rate_estimate
type: object
description: A rate estimate
required:
- rate_type
- carrier_id
- shipping_amount
- insurance_amount
- confirmation_amount
- other_amount
- zone
- package_type
- guaranteed_service
- negotiated_rate
- service_type
- service_code
- trackable
- carrier_code
- carrier_nickname
- carrier_friendly_name
- validation_status
- warning_messages
- error_messages
additionalProperties: false
properties:
rate_type:
readOnly: true
allOf:
- $ref: '#/components/schemas/rate_type'
carrier_id:
readOnly: true
allOf:
- $ref: '#/components/schemas/se_id'
description: A string that uniquely identifies the carrier
shipping_amount:
readOnly: true
allOf:
- $ref: '#/components/schemas/monetary_value'
description: The shipping amount
insurance_amount:
readOnly: true
allOf:
- $ref: '#/components/schemas/monetary_value'
description: The insurance amount
confirmation_amount:
readOnly: true
allOf:
- $ref: '#/components/schemas/monetary_value'
description: The confirmation amount
other_amount:
readOnly: true
allOf:
- $ref: '#/components/schemas/monetary_value'
description: Any other charges associated with this rate
tax_amount:
readOnly: true
allOf:
- $ref: '#/components/schemas/monetary_value'
description: >-
Tariff and additional taxes associated with an international
shipment.
zone:
type: integer
format: int32
nullable: true
readOnly: true
minimum: 0
example: 6
description: >
Certain carriers base [their
rates](https://blog.stamps.com/2017/09/08/usps-postal-zones/) off of
custom zones that vary depending upon the ship_to and ship_from
location
package_type:
type: string
nullable: true
readOnly: true
minLength: 1
example: package
description: package type that this rate was estimated for
delivery_days:
type: integer
format: int32
readOnly: true
minimum: 1
example: 5
description: >
The number of days estimated for delivery, this will show the
_actual_ delivery
time if for example, the package gets shipped on a Friday
guaranteed_service:
type: boolean
readOnly: true
description: Indicates if the rate is guaranteed.
estimated_delivery_date:
readOnly: true
allOf:
- $ref: '#/components/schemas/date'
carrier_delivery_days:
type: string
readOnly: true
minLength: 1
description: The carrier delivery days
ship_date:
type: string
format: date-time
readOnly: true
minLength: 1
description: ship date
negotiated_rate:
type: boolean
readOnly: true
description: Indicates if the rates been negotiated
service_type:
type: string
readOnly: true
minLength: 1
description: service type
service_code:
type: string
readOnly: true
minLength: 1
description: service code for the rate
trackable:
type: boolean
readOnly: true
description: Indicates if rate is trackable
carrier_code:
type: string
readOnly: true
minLength: 1
description: >-
A [shipping
carrier](https://www.shipengine.com/docs/carriers/setup/), such as
`fedex`, `dhl_express`, `stamps_com`, etc.
carrier_nickname:
type: string
readOnly: true
minLength: 1
description: carrier nickname
carrier_friendly_name:
type: string
readOnly: true
minLength: 1
description: carrier friendly name
validation_status:
readOnly: true
allOf:
- $ref: '#/components/schemas/validation_status'
warning_messages:
type: array
readOnly: true
minItems: 0
items:
type: string
readOnly: true
minLength: 0
description: warning message
description: The warning messages
error_messages:
type: array
readOnly: true
minItems: 0
items:
type: string
readOnly: true
minLength: 0
description: error message
description: The error messages
get_rate_by_id_response_body:
title: get_rate_by_id_response_body
type: object
description: A rate response body
required:
- rates
- invalid_rates
- rate_request_id
- shipment_id
- created_at
- status
- errors
additionalProperties: false
allOf:
- $ref: '#/components/schemas/rate'
get_service_points_request:
title: get_service_points_request
oneOf:
- $ref: '#/components/schemas/get_service_points_request_body'
get_service_points_request_body:
title: get_service_points_request_body
type: object
description: >-
A get service points request body. Caller must provide exactly one of
address_query, address, or lat / long pair.
required:
- providers
properties:
address_query:
type: string
description: Unstructured text to search for service points by.
example: 177A Bleecker Street New York
address:
type: object
description: Structured address to search by.
required:
- country_code
properties:
address_line1:
type: string
example: 1999 Bishop Grandin Blvd.
description: >-
The first line of the street address. For some addresses, this
may be the only line. Other addresses may require 2 or 3 lines.
address_line2:
type: string
address_line3:
type: string
city_locality:
type: string
description: The name of the city or locality
state_province:
type: string
description: >-
The state or province. For some countries (including the U.S.)
only abbreviations are allowed. Other countries allow the full
name or abbreviation.
postal_code:
type: string
allOf:
- $ref: '#/components/schemas/postal_code'
country_code:
type: string
allOf:
- $ref: '#/components/schemas/country_code'
providers:
type: array
description: An array of shipping service providers and service codes
items:
type: object
properties:
carrier_id:
type: string
example: se-123456
description: Uniquely identifies a carrier connection
service_code:
type: array
items:
type: string
example: chronoclassic
description: Uniquely identifies a shipping service
lat:
format: double
type: number
example: 48.874518928233094
description: >-
The latitude of the point. Represented as signed degrees. Required
if long is provided. http://www.geomidpoint.com/latlon.html
long:
format: double
type: number
example: 2.3591775711639404
description: >-
The longitude of the point. Represented as signed degrees. Required
if lat is provided. http://www.geomidpoint.com/latlon.html
radius:
format: int32
type: integer
example: 500
description: Search radius in kilometers
max_results:
format: int32
type: integer
example: 25
description: The maximum number of service points to return
list_service_points_response_body:
title: list_service_points_response_body
type: object
description: A list service points response body
properties:
lat:
format: double
type: number
example: 48.842608
description: >-
The latitude of the point. Represented as signed degrees. Required
if long is provided. http://www.geomidpoint.com/latlon.html
long:
format: double
type: number
example: 0.032875
description: >-
The longitude of the point. Represented as signed degrees. Required
if lat is provided. http://www.geomidpoint.com/latlon.html
service_points:
type: array
items:
type: object
properties:
carrier_code:
allOf:
- $ref: '#/components/schemas/carrier_code'
service_codes:
type: array
items:
type: string
example: chronoclassic
description: >-
A [shipping
carrier](https://www.shipengine.com/docs/carriers/setup/)
service code.
service_point_id:
type: string
example: '614940'
description: A unique identifier for a carrier drop off point.
company_name:
type: string
example: My fancy company name
description: >-
If this is a business address, then the company name should be
specified here.
address_line1:
type: string
example: PLACE DU CANADA
description: >-
The first line of the street address. For some addresses,
this may be the only line. Other addresses may require 2 or 3
lines.
city_locality:
type: string
example: TRUN
description: The name of the city or locality
state_province:
type: string
example: TRUN
description: >-
The state or province. For some countries (including the U.S.)
only abbreviations are allowed. Other countries allow the full
name or abbreviation.
postal_code:
allOf:
- $ref: '#/components/schemas/postal_code'
country_code:
allOf:
- $ref: '#/components/schemas/country_code'
phone_number:
type: string
example: 555-555-5555
description: Phone number associated
lat:
format: double
type: number
example: 48.842608
description: >-
The latitude of the point. Represented as signed degrees.
Required if long is provided.
http://www.geomidpoint.com/latlon.html
long:
format: double
type: number
example: 0.032875
description: >-
The longitude of the point. Represented as signed degrees.
Required if lat is provided.
http://www.geomidpoint.com/latlon.html
distance_in_meters:
format: double
type: number
example: 728.9959308847579
description: Distance in meters
hours_of_operation:
type: object
description: Hours of operation
properties:
monday:
type: array
items:
type: object
properties:
open:
type: string
example: '09:15'
description: Opening time
close:
type: string
example: '12:00'
description: Closing time
tuesday:
type: array
items:
type: object
properties:
open:
type: string
example: '09:15'
description: Opening time
close:
type: string
example: '12:00'
description: Closing time
wednesday:
type: array
items:
type: object
properties:
open:
type: string
example: '09:15'
description: Opening time
close:
type: string
example: '12:00'
description: Closing time
thursday:
type: array
items:
type: object
properties:
open:
type: string
example: '09:15'
description: Opening time
close:
type: string
example: '12:00'
description: Closing time
friday:
type: array
items:
type: object
properties:
open:
type: string
example: '09:15'
description: Opening time
close:
type: string
example: '12:00'
description: Closing time
saturday:
type: array
items:
type: object
properties:
open:
type: string
example: '09:15'
description: Opening time
close:
type: string
example: '12:00'
description: Closing time
sunday:
type: array
items:
type: object
properties:
open:
type: string
example: '09:15'
description: Opening time
close:
type: string
example: '12:00'
description: Closing time
features:
type: array
description: Service features
items:
type: string
enum:
- drop_off_point
- pickup_point
- print_services
- after_hours_locker
- after_hours_dropbox
type:
type: string
description: Service point type
default: pudo
enum:
- pudo
- locker
errors:
type: array
readOnly: true
items:
allOf:
- $ref: '#/components/schemas/error'
description: The errors associated with the failed API call
get_service_point_by_id_response_body:
title: get_service_point_by_id_response_body
type: object
description: A get service point by ID response body
properties:
service_point:
type: object
properties:
carrier_code:
allOf:
- $ref: '#/components/schemas/carrier_code'
service_codes:
type: array
items:
type: string
description: >-
A [shipping
carrier](https://www.shipengine.com/docs/carriers/setup/)
service code.
service_point_id:
type: string
example: '614940'
description: A unique identifier for a carrier drop off point.
company_name:
type: string
example: My fancy company name
description: >-
If this is a business address, then the company name should be
specified here.
address_line1:
type: string
example: PLACE DU CANADA
description: >-
The first line of the street address. For some addresses, this
may be the only line. Other addresses may require 2 or 3 lines.
city_locality:
type: string
example: TRUN
description: The name of the city or locality
state_province:
type: string
example: TRUN
description: >-
The state or province. For some countries (including the U.S.)
only abbreviations are allowed. Other countries allow the full
name or abbreviation.
postal_code:
allOf:
- $ref: '#/components/schemas/postal_code'
country_code:
allOf:
- $ref: '#/components/schemas/country_code'
phone_number:
type: string
example: 555-555-5555
description: Phone number associated
lat:
format: double
type: number
example: 48.842608
description: >-
The latitude of the point. Represented as signed degrees.
Required if long is provided.
http://www.geomidpoint.com/latlon.html
long:
format: double
type: number
example: 0.032875
description: >-
The longitude of the point. Represented as signed degrees.
Required if lat is provided.
http://www.geomidpoint.com/latlon.html
hours_of_operation:
type: object
description: Hours of operation
properties:
monday:
type: array
items:
type: object
properties:
open:
type: string
example: '09:15'
description: Opening time
close:
type: string
example: '12:00'
description: Closing time
tuesday:
type: array
items:
type: object
properties:
open:
type: string
example: '09:15'
description: Opening time
close:
type: string
example: '12:00'
description: Closing time
wednesday:
type: array
items:
type: object
properties:
open:
type: string
example: '09:15'
description: Opening time
close:
type: string
example: '12:00'
description: Closing time
thursday:
type: array
items:
type: object
properties:
open:
type: string
example: '09:15'
description: Opening time
close:
type: string
example: '12:00'
description: Closing time
friday:
type: array
items:
type: object
properties:
open:
type: string
example: '09:15'
description: Opening time
close:
type: string
example: '12:00'
description: Closing time
saturday:
type: array
items:
type: object
properties:
open:
type: string
example: '09:15'
description: Opening time
close:
type: string
example: '12:00'
description: Closing time
sunday:
type: array
items:
type: object
properties:
open:
type: string
example: '09:15'
description: Opening time
close:
type: string
example: '12:00'
description: Closing time
features:
type: array
description: Service features
items:
type: string
enum:
- drop_off_point
- pickup_point
- print_services
- after_hours_locker
- after_hours_dropbox
type:
type: string
description: Service point type
default: pudo
enum:
- pudo
- locker
shipments_sort_by:
title: shipments_sort_by
type: string
enum:
- modified_at
- created_at
description: The possible shipments sort by values
list_shipments_response_body:
title: list_shipments_response_body
type: object
description: A list shipment response body
required:
- shipments
- total
- page
- pages
- links
additionalProperties: false
properties:
shipments:
type: array
readOnly: true
items:
readOnly: true
allOf:
- $ref: '#/components/schemas/shipment'
description: A shipment object
description: The list of shipments returned by the api call
total:
type: integer
format: int64
readOnly: true
minimum: 0
example: 1990
description: Total number of shipments returned by the api call
page:
type: integer
format: int32
readOnly: true
minimum: 1
example: '????'
pages:
type: integer
format: int32
readOnly: true
minimum: 1
links:
readOnly: true
allOf:
- $ref: '#/components/schemas/pagination_link'
create_shipments_request_body:
title: create_shipments_request_body
type: object
description: A create shipments request body
required:
- shipments
additionalProperties: false
properties:
shipments:
type: array
minItems: 1
items:
allOf:
- $ref: '#/components/schemas/address_validating_shipment'
description: An array of shipments to be created.
create_shipments_response_body:
title: create_shipments_response_body
type: object
description: A create shipments response body
required:
- has_errors
- shipments
additionalProperties: false
properties:
has_errors:
type: boolean
default: false
description: Indicates if errors occured while creating the shipments
shipments:
type: array
items:
allOf:
- $ref: '#/components/schemas/create_and_validate_shipment'
description: The shipment that was created.
description: An array of shipments that were created.
create_and_validate_shipment:
title: create_and_validate_shipment
type: object
description: A create and validate shipment resource
additionalProperties: false
allOf:
- $ref: '#/components/schemas/partial_shipment'
- $ref: '#/components/schemas/create_shipment_response_body_fields'
create_shipment_response_body_fields:
title: create_shipment_response_body_fields
type: object
properties:
errors:
type: array
deprecated: true
items:
type: string
minLength: 1
example: Parameter value '100000000.00' is out of range.
description: An error that occurred while creating a shipment.
description: An array of errors that occurred while creating shipment.
readOnly: true
address_validation:
allOf:
- $ref: '#/components/schemas/address_validation_result'
description: The address validation
get_shipment_by_external_id_response_body:
title: get_shipment_by_external_id_response_body
type: object
description: A get shipment by external id response body
additionalProperties: false
allOf:
- $ref: '#/components/schemas/shipment'
parse_shipment_request_body:
title: parse_shipment_request_body
type: object
description: >
The only required field is `text`, which is the text to be parsed. You
can optionally also provide a `shipment` containing any already-known
values. For example, you probably already know the `ship_from` address,
and you may also already know what carrier and service you want to use.
required:
- text
additionalProperties: false
properties:
text:
type: string
minLength: 1
example: >
I have a 4oz package that's 5x10x14in, and I need to ship it to
Margie McMiller at 3800 North Lamar suite 200 in austin, tx 78652.
Please send it via USPS first class and require an adult signature.
It also needs to be insured for $400.
description: The unstructured text that contains shipping-related entities
shipment:
allOf:
- $ref: '#/components/schemas/partial_shipment'
description: >
You can optionally provide a `shipment` object containing any
already-known values. For example, you probably already know the
`ship_from` address, and you may also already know what carrier and
service you want to use.
parse_shipment_response_body:
title: parse_shipment_response_body
type: object
description: >
The parsed shipment, as well as a confidence score and a list of all the
shipping entities that were recognized in the text.
required:
- score
- shipment
- entities
additionalProperties: false
properties:
score:
type: number
format: double
minimum: 0
maximum: 1
description: >
A confidence score between zero and one that indicates how certain
the API is that it understood the text.
shipment:
allOf:
- $ref: '#/components/schemas/partial_shipment'
description: >
The parsed shipment. This shipment may not be complete, depending
on how much information was included in the text and how confident
the API is about each recognized entity.
> **Note:** The shipment-recognition API does not currently perform
any validation of the parsed addresses, so we recommend that you use
the [address-validation
API](https://www.shipengine.com/docs/addresses/validation/) to
ensure that the addresses are correct.
entities:
type: array
minItems: 0
items:
$ref: '#/components/schemas/recognized_entity'
description: >
All of the entities that were recognized in the text. An "entity" is
a single piece of data, such as a city, a postal code, a carrier
name, or a package weight. Each entity includes the original text
and the parsed value.
get_shipment_by_id_response_body:
title: get_shipment_by_id_response_body
type: object
description: A get shipment by id response body
additionalProperties: false
allOf:
- $ref: '#/components/schemas/shipment'
update_shipment_request_body:
title: update_shipment_request_body
type: object
description: An update shipment request body
required:
- ship_to
- ship_from
additionalProperties: false
allOf:
- $ref: '#/components/schemas/partial_shipment'
- $ref: '#/components/schemas/update_shipment_fields'
update_shipment_fields:
title: update_shipment_fields
type: object
properties:
validate_address:
default: no_validation
allOf:
- $ref: '#/components/schemas/validate_address'
update_shipment_response_body:
title: update_shipment_response_body
type: object
description: An update shipment response body
required:
- errors
- has_errors
- address_validation
- shipment_id
- carrier_id
- service_code
- ship_date
- created_at
- shipment_status
- ship_to
- ship_from
- return_to
- confirmation
- customs
- advanced_options
- insurance_provider
- tags
- packages
- total_weight
additionalProperties: false
allOf:
- $ref: '#/components/schemas/create_and_validate_shipment'
list_shipment_rates_response_body:
title: list_shipment_rates_response_body
type: object
description: A list shipment rates response body
required:
- rates
- invalid_rates
- rate_request_id
- shipment_id
- created_at
- status
- errors
additionalProperties: false
allOf:
- $ref: '#/components/schemas/rates_information'
update_shipments_tags_request_body:
title: update_shipments_tags_request_body
type: object
description: A request body with shipments and tags
allOf:
- $ref: '#/components/schemas/update_shipments_tags'
update_shipments_tags:
title: update_shipments_tags
type: object
properties:
shipments_tags:
type: array
items:
type: object
properties:
shipment_id:
type: string
tags:
type: array
items:
type: string
example:
shipments_tags:
- shipment_id: se-1014296
tags:
- Fragile
- International
- shipment_id: se-1014297
tags:
- Fragile
- International
tag_shipment_response_body:
title: tag_shipment_response_body
type: object
description: Get shipment tags response body
required:
- tags
additionalProperties: false
properties:
tags:
type: array
items:
type: string
tag_name:
title: tag_name
type: string
minLength: 1
example: Fragile
description: >
Tags are arbitrary strings that you can use to categorize shipments.
For example, you may want to use tags to distinguish between domestic
and international shipments, or between insured and uninsured
shipments. Or maybe you want to create a tag for each of your customers
so you can easily retrieve every shipment for a customer.
list_tags_response_body:
title: list_tags_response_body
type: object
description: Response body from a successful GET /tags API call
additionalProperties: false
properties:
tags:
type: array
items:
allOf:
- $ref: '#/components/schemas/tag'
description: The array of tags returned by the API call
create_tag_response_body:
title: create_tag_response_body
type: object
description: Response body for creating tags
additionalProperties: false
allOf:
- $ref: '#/components/schemas/tag'
redirect:
title: redirect
type: string
enum:
- shipengine-dashboard
description: The resource to return a redirect URL to.
tokens_get_ephemeral_token_response_body.yaml:
title: tokens_get_ephemeral_token_response_body.yaml
type: object
properties:
token:
type: string
description: The requested token that expires in 10 seconds.
redirect_url:
type: string
description: The redirect url formatted with the requested token.
get_tracking_log_response_body:
title: get_tracking_log_response_body
type: object
description: A get tracking log response body
required:
- tracking_number
- tracking_url
- status_code
- carrier_code
- carrier_id
- carrier_detail_code
- carrier_status_code
- estimated_delivery_date
- events
additionalProperties: false
allOf:
- $ref: '#/components/schemas/tracking_information'
list_warehouses_response_body:
title: list_warehouses_response_body
type: object
description: A warehouse list response body
required:
- warehouses
additionalProperties: false
properties:
warehouses:
type: array
readOnly: true
items:
readOnly: true
allOf:
- $ref: '#/components/schemas/warehouse'
description: The array of warehouses returned by the API call
warehouse:
title: warehouse
type: object
description: A warehouse
additionalProperties: false
properties:
warehouse_id:
readOnly: true
allOf:
- $ref: '#/components/schemas/se_id'
description: A string that uniquely identifies the warehouse
is_default:
nullable: true
type: boolean
default: false
description: Designates which single warehouse is the default on the account
name:
type: string
minLength: 1
example: Zero Cool HQ
description: Name of the warehouse
created_at:
type: string
format: date-time
readOnly: true
example: '2019-06-25T18:12:35.583Z'
minLength: 1
description: Timestamp that indicates when the warehouse was created
origin_address:
allOf:
- $ref: '#/components/schemas/address'
description: The origin address of the warehouse
return_address:
allOf:
- $ref: '#/components/schemas/address'
description: The return address associated with the warehouse
create_warehouse_request_body:
title: create_warehouse_request_body
type: object
description: A create warehouse request body
required:
- name
- origin_address
additionalProperties: false
allOf:
- $ref: '#/components/schemas/warehouse'
create_warehouse_response_body:
title: create_warehouse_response_body
type: object
description: A create warehouse response body
required:
- warehouse_id
- name
- created_at
- origin_address
- return_address
additionalProperties: false
allOf:
- $ref: '#/components/schemas/warehouse'
get_warehouse_by_id_response_body:
title: get_warehouse_by_id_response_body
type: object
description: A get warehouse by id response body
required:
- warehouse_id
- name
- created_at
- origin_address
- return_address
additionalProperties: false
allOf:
- $ref: '#/components/schemas/warehouse'
update_warehouse_request_body:
title: update_warehouse_request_body
type: object
description: An update warehouse request body
required:
- name
- origin_address
additionalProperties: false
allOf:
- $ref: '#/components/schemas/warehouse'
update_warehouse_settings_request_body:
title: update_warehouse_settings_request_body
type: object
description: An update warehouse settings request body
properties:
is_default:
type: boolean
nullable: true
description: The default property on the warehouse.
example: true
additionalProperties: false
responses:
400_error_response:
description: The request contained errors.
content:
application/json:
schema:
$ref: '#/components/schemas/error_response_body'
404_error_response:
description: The specified resource does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/error_response_body'
500_error_response:
description: |
An error occurred on ShipEngine's side.
> This error will automatically be reported to our engineers.
content:
application/json:
schema:
$ref: '#/components/schemas/error_response_body'
409_error_response:
description: The request conflicts with an existing resource.
content:
application/json:
schema:
$ref: '#/components/schemas/error_response_body'
securitySchemes:
api_key:
type: apiKey
name: API-Key
in: header
description: >
To authenticate yourself to ShipEngine, you need to include an `API-Key`
header in each API call. If you don't include a key when making an API
request, or if you use an incorrect or expired key, then ShipEngine will
respond with a `401 Unauthorized` error.
Learn more about API keys in our [authentication
guide](https://www.shipengine.com/docs/auth/).
tags:
- name: account
description: |
For additional information about the ShipEngine account.
x-displayName: Account
- name: addresses
description: >
No matter your shipping volume, failed deliveries and address change
surcharges cut into your bottom line and damage perception with customers.
Our address validation services ensure your packages make it to the right
place the first time. [Learn how to leverage our address validation
services here.](https://www.shipengine.com/docs/addresses/validation/)
ShipEngine supports address validation for virtually every country on
Earth, including the United States, Canada, Great Britain, Australia,
Germany, France, Norway, Spain, Sweden, Israel, Italy, and over 160
others.
externalDocs:
url: 'https://www.shipengine.com/docs/addresses/validation/'
description: >
Address validation ensures accurate addresses and can lead to reduced
shipping costs by preventing address correction surcharges. ShipEngine
cross references multiple databases to validate addresses and identify
potential deliverability issues.
x-displayName: Addresses
- name: batches
description: |
batches
x-displayName: Batches
- name: carrier_accounts
description: |
carrier accounts
x-displayName: Carrier Accounts
- name: carriers
description: |
carriers
x-displayName: Carriers
- name: downloads
description: |
downloads
x-displayName: Downloads
- name: insurance
description: |
insurance
x-displayName: Insurance
- name: labels
description: >
Print shipping labels for any of the top global carriers in
minutes—instead of weeks. Simply [connect your existing carrier
accounts](https://www.shipengine.com/docs/carriers/setup/) in the API
dashboard, and then [begin creating
labels](https://www.shipengine.com/docs/shipping/use-a-carrier-service/).
externalDocs:
url: 'https://www.shipengine.com/docs/labels/create-a-label/'
description: >-
Follow this quick start guide to create your first shipping label with
ShipEngine
x-displayName: Labels
- name: manifests
description: |
manifests
x-displayName: Manifests
- name: package_pickups
description: Scheduled package pickups
x-displayName: Package Pickups
- name: package_types
description: |
custom package types
x-displayName: Package Types
- name: rates
description: >
Make sure you ship as cost-effectively as possible by [quickly comparing
rates](https://www.shipengine.com/docs/rates/) using the ShipEngine Rates
API. As long as you have the carrier connected to your account, you'll be
able to see and compare different rates and services.
externalDocs:
url: 'https://www.shipengine.com/docs/rates/'
description: >
This quick start guide shows you how to get shipping rates for multiple
carriers so you can choose the fastest, cheapest, or most reliable
option.
x-displayName: Rates
- name: service_points
x-displayName: Service Points
- name: shipments
description: >
Shipments are at the center of the ShipEngine API. A shipment is the
first step in [creating a shipping
label](https://www.shipengine.com/docs/labels/create-a-label/), or
[creating a
manifest](https://www.shipengine.com/docs/shipping/manifests/). It's also
essential for [getting shipping
rates](https://www.shipengine.com/docs/rates/).
externalDocs:
url: 'https://www.shipengine.com/docs/shipping/create-a-shipment/'
description: >
Learn about the shipment object model concept, and how to persist and
re-use shipment data inside ShipEngine.
x-displayName: Shipments
- name: tags
description: |
tags
x-displayName: Tags
- name: tokens
x-displayName: Tokens
- name: tracking
description: >
[Track packages](https://www.shipengine.com/docs/tracking/) across any of
our 20+ supported carrier accounts and create tracking events to keep your
customers up-to-date. Easily integrate real-time tracking information for
shipments into your app, email, or SMS.
externalDocs:
url: 'https://www.shipengine.com/docs/tracking/'
description: >-
Learn how to use ShipEngine to track any package with a carrier and a
tracking number
x-displayName: Tracking
- name: warehouses
description: |
warehouses
x-displayName: Warehouses
- name: webhooks
description: >
[Webhooks](https://www.shipengine.com/docs/tracking/webhooks/) are a
powerful feature of ShipEngine that can save you from sending repeated
polling requests to check on the state of something. With webhooks,
ShipEngine will automatically contact your servers when the stage
changes. This can include [parcel
tracking](https://www.shipengine.com/docs/tracking/) events, notification
of the completion of a [batch
operation](https://www.shipengine.com/docs/labels/bulk/), or new [salses
orders](https://www.shipengine.com/docs/orders/).
externalDocs:
url: 'https://www.shipengine.com/docs/tracking/webhooks/'
description: Learn how to setup webhooks and start listening to ShipEngine events.
x-displayName: Webhooks
security:
- api_key: []
externalDocs:
url: 'https://www.shipengine.com/docs/'
description: >
ShipEngine's documentation is designed to help you start shipping as quickly
as possible. With easy-to-follow tutorials, detailed reference docs, and
ready-made recipes for common use cases, you'll see real results in no time
at all.