Shippo external API.

Shipping and logistics API

docs.goshippo.com ↗

Version

2018-02-08

OpenAPI

3.0.3

Endpoints

Schemas

213

81

Quality

Updated

3 days ago

Shipping shipping logistics ecommerce

Use this API in your AI agent

Query structured spec data via REST or MCP. Get exactly what your agent needs.

Get API Key

Server URLs

https://api.goshippo.com

Endpoints

GET POST PUT PATCH DELETE

Addresses 4 endpoints

GET /addresses List all addresses

Returns a list of all address objects that have been created in this account.

operationId: Addresses_listAll

Parameters

Name	In	Required	Type	Description
page	query	optional	integer	The page number you want to select
results	query	optional	integer	The number of results to return per page (max 100, default 5)
SHIPPO-API-VERSION	header	optional	string	String used to pick a non-default API version to use

Responses

200 —

GET /addresses

POST /addresses Create a new address

Creates a new address object. You can use address objects to create new shipments, calculate rates, and to create orders.

operationId: Addresses_createNewAddress

Parameters

Name	In	Required	Type	Description
SHIPPO-API-VERSION	header	optional	string	String used to pick a non-default API version to use

Request Body

Address details.

application/json

schema AddressCreateRequest

Property	Type	Required
zip	string	optional
city	string	optional
name	string	optional
email	string	optional
phone	string	optional
state	string	optional
company	string	optional
country	string	required
street1	string	optional
street2	string	optional
street3	string	optional
latitude	number	optional
metadata	string	optional
longitude	number	optional
street_no	string	optional
is_residential	boolean	optional
validate	boolean	optional

Responses

201 —

POST /addresses

GET /addresses/{AddressId} Retrieve an address

Returns an existing address using an object ID.

operationId: Addresses_getAddressById

Parameters

Name	In	Required	Type	Description
AddressId	path	required	string	Object ID of the address
SHIPPO-API-VERSION	header	optional	string	String used to pick a non-default API version to use

Responses

200 —

GET /addresses/{AddressId}

GET /addresses/{AddressId}/validate Validate an address

Validates an existing address using an object ID

operationId: Addresses_validateAddress

Parameters

Name	In	Required	Type	Description
AddressId	path	required	string	Object ID of the address
SHIPPO-API-VERSION	header	optional	string	String used to pick a non-default API version to use

Responses

200 —

GET /addresses/{AddressId}/validate

Batches 5 endpoints

POST /batches Create a batch

Creates a new batch object for purchasing shipping labels for many shipments at once. Batches are created asynchronously. This means that the API response won’t include your batch shipments yet. You need to retrieve the batch later to verify that all batch shipments are valid.

operationId: Batches_createBatchShipments

Parameters

Name	In	Required	Type	Description
SHIPPO-API-VERSION	header	optional	string	String used to pick a non-default API version to use

Request Body

Batch details.

application/json

schema BatchCreateRequest

Property	Type	Required
metadata	string	optional
label_filetype	string	optional
default_carrier_account	string	required
default_servicelevel_token	string	required
batch_shipments	array	required
└ metadata	string	optional
└ shipment	object	required
└ extra	object	optional
└ COD	object	optional
└ alcohol	object	optional
└ billing	object	optional
└ dry_ice	object	optional
└ premium	boolean	optional
└ insurance	object	optional
└ is_return	boolean	optional
└ po_number	object	optional
└ rma_number	object	optional
└ dept_number	object	optional
└ reference_1	string	optional
└ reference_2	string	optional
└ carbon_neutral	boolean	optional
└ carrier_hub_id	string	optional
└ container_type	string	optional
└ invoice_number	object	optional
└ customer_branch	string	optional
└ dangerous_goods	object	optional
└ lasership_attrs	string	optional
└ qr_code_requested	boolean	optional
└ …15 more	object	optional
└ metadata	string	optional
└ shipment_date	string	optional
└ customs_declaration	string	optional
└ async	boolean	optional
└ parcels	array	required
└ address_to	object	required
└ address_from	object	required
└ address_return	object	optional
└ carrier_accounts	array	optional
└ carrier_account	string	optional
└ servicelevel_token	string	optional

Responses

200 —

POST /batches

GET /batches/{BatchId} Retrieve a batch

Returns a batch using an object ID.
Batch shipments are displayed 100 at a time. You can iterate
through each page using the ?page= query parameter. You can also filter based on batch shipment
status, for example, by passing a query param like ?object_results=creation_failed.

For more details on filtering results, see our guide on filtering.

operationId: Batches_getBatchById

Parameters

Name	In	Required	Type	Description
BatchId	path	required	string	Object ID of the batch
SHIPPO-API-VERSION	header	optional	string	String used to pick a non-default API version to use

Responses

200 —

GET /batches/{BatchId}

POST /batches/{BatchId}/add_shipments Add shipments to a batch

Adds batch shipments to an existing batch.

operationId: Batches_addShipmentsToBatch

Parameters

Name	In	Required	Type	Description
BatchId	path	required	string	Object ID of the batch
SHIPPO-API-VERSION	header	optional	string	String used to pick a non-default API version to use

Request Body

Array of shipments to add to the batch

application/json

schema BatchesAddShipmentsToBatchRequest

array of object

Property	Type	Required
metadata	string	optional
shipment	object	required
└ extra	object	optional
└ COD	object	optional
└ amount	string	optional
└ currency	string	optional
└ payment_method	string	optional
└ alcohol	object	optional
└ recipient_type	string	optional
└ contains_alcohol	boolean	optional
└ billing	object	optional
└ zip	string	optional
└ type	string	optional
└ account	string	optional
└ country	string	optional
└ participation_code	string	optional
└ dry_ice	object	optional
└ weight	string	optional
└ contains_dry_ice	boolean	optional
└ premium	boolean	optional
└ insurance	object	optional
└ amount	string	optional
└ content	string	optional
└ currency	string	optional
└ provider	string	optional
└ is_return	boolean	optional
└ po_number	object	optional
└ value	string	optional
└ prefix	string	optional
└ rma_number	object	optional
└ value	string	optional
└ prefix	string	optional
└ dept_number	object	optional
└ value	string	optional
└ prefix	string	optional
└ reference_1	string	optional
└ reference_2	string	optional
└ carbon_neutral	boolean	optional
└ carrier_hub_id	string	optional
└ container_type	string	optional
└ invoice_number	object	optional
└ value	string	optional
└ prefix	string	optional
└ customer_branch	string	optional
└ dangerous_goods	object	optional
└ contains	boolean	optional
└ lithium_batteries	object	optional
└ biological_material	object	optional
└ lasership_attrs	string	optional
└ qr_code_requested	boolean	optional
└ …15 more	object	optional
└ metadata	string	optional
└ shipment_date	string	optional
└ customs_declaration	string	optional
└ async	boolean	optional
└ parcels	array	required
└ address_to	object	required
└ address_from	object	required
└ address_return	object	optional
└ carrier_accounts	array	optional
carrier_account	string	optional
servicelevel_token	string	optional

Responses

200 —

POST /batches/{BatchId}/add_shipments

POST /batches/{BatchId}/purchase Purchase a batch

Purchases an existing batch with a status of VALID.
Once you send a POST request to the purchase endpoint the batch status will change to PURCHASING.
When all the shipments are purchased, the status will change to PURCHASED and you will receive a
batch_purchased webhook indicating that the batch has been purchased

operationId: Batches_purchaseBatch

Parameters

Name	In	Required	Type	Description
BatchId	path	required	string	Object ID of the batch
SHIPPO-API-VERSION	header	optional	string	String used to pick a non-default API version to use

Responses

200 —

POST /batches/{BatchId}/purchase

POST /batches/{BatchId}/remove_shipments Remove shipments from a batch

Removes shipments from an existing batch shipment.

operationId: Batches_removeShipments

Parameters

Name	In	Required	Type	Description
BatchId	path	required	string	Object ID of the batch
SHIPPO-API-VERSION	header	optional	string	String used to pick a non-default API version to use

Request Body

Array of shipments object ids to remove from the batch

application/json

schema BatchesRemoveShipmentsRequest

array of string

Responses

200 —

POST /batches/{BatchId}/remove_shipments

Carrieraccounts 7 endpoints

GET /carrier_accounts List all carrier accounts

Returns a list of all carrier accounts connected to your Shippo account. These carrier accounts include both Shippo carrier accounts and your own carrier accounts that you have connected to your Shippo account.

Additionally, you can get information about the service levels associated with each carrier account by passing in the ?service_levels=true query parameter.

Using it appends the property service_levels to each carrier account.

By default, if the query parameter is omitted, the service_levels property will not be included in the response.

operationId: CarrierAccounts_listAllAccounts

Parameters

Name	In	Required	Type	Description
service_levels	query	optional	boolean	Appends the property `service_levels` to each returned carrier account
carrier	query	optional		Filter the response by the specified carrier
account_id	query	optional	string	Filter the response by the specified carrier account Id
page	query	optional	integer	The page number you want to select
results	query	optional	integer	The number of results to return per page (max 100, default 5)
SHIPPO-API-VERSION	header	optional	string	String used to pick a non-default API version to use

Responses

200 —

GET /carrier_accounts

POST /carrier_accounts Create a new carrier account

Creates a new carrier account or connects an existing carrier account to the Shippo account.

operationId: CarrierAccounts_createNewAccount

Parameters

Name	In	Required	Type	Description
SHIPPO-API-VERSION	header	optional	string	String used to pick a non-default API version to use

Request Body

Examples.

application/json

schema ConnectExistingOwnAccountRequest

Property	Type	Required
test	boolean	optional
active	boolean	optional
carrier	string	required
metadata	string	optional
account_id	string	required
parameters	object	required

Responses

201 —

400 —

POST /carrier_accounts

GET /carrier_accounts/reg-status Get Carrier Registration status

Returns the registration status for the given account for the given carrier

operationId: CarrierAccounts_getRegStatus

Parameters

Name	In	Required	Type	Description
carrier	query	required	string	filter by specific carrier
SHIPPO-API-VERSION	header	optional	string	String used to pick a non-default API version to use

Responses

200 —

GET /carrier_accounts/reg-status

POST /carrier_accounts/register/new Add a Shippo carrier account

Adds a Shippo carrier account

operationId: CarrierAccounts_addShippoAccount

Parameters

Name	In	Required	Type	Description
SHIPPO-API-VERSION	header	optional	string	String used to pick a non-default API version to use

Request Body

Examples.

application/json

schema CarrierAccountsAddShippoAccountRequest

Responses

201 —

400 —

POST /carrier_accounts/register/new

GET /carrier_accounts/{CarrierAccountId} Retrieve a carrier account

Returns an existing carrier account using an object ID.

operationId: CarrierAccounts_getAccountById

Parameters

Name	In	Required	Type	Description
CarrierAccountId	path	required	string	Object ID of the carrier account
SHIPPO-API-VERSION	header	optional	string	String used to pick a non-default API version to use

Responses

200 —

GET /carrier_accounts/{CarrierAccountId}

PUT /carrier_accounts/{CarrierAccountId} Update a carrier account

Updates an existing carrier account object. The account_id and carrier can’t be updated. This is because they form the unique identifier together.

operationId: CarrierAccounts_updateAccount

Parameters

Name	In	Required	Type	Description
CarrierAccountId	path	required	string	Object ID of the carrier account
SHIPPO-API-VERSION	header	optional	string	String used to pick a non-default API version to use

Request Body

Examples.

application/json

schema CarrierAccountBase

Property	Type	Required
active	boolean	optional
carrier	string	required
account_id	string	required
parameters	object	optional

Responses

200 —

PUT /carrier_accounts/{CarrierAccountId}

GET /carrier_accounts/{CarrierAccountObjectId}/signin/initiate Connect an existing carrier account using OAuth 2.0

Used by client applications to setup or reconnect an existing carrier account with carriers that support OAuth 2.0

operationId: CarrierAccounts_initiateSignIn

Parameters

Name	In	Required	Type	Description
CarrierAccountObjectId	path	required	string	The carrier account ID to start a signin process
redirect_uri	query	required	string	Callback URL. The URL that tells the authorization server where to send the user back to after they approve the request.
state	query	optional	string	A random string generated by the consuming application and included in the request to prevent CSRF attacks. The consuming application checks that the same value is returned after the user authorizes Shippo.
SHIPPO-API-VERSION	header	optional	string	String used to pick a non-default API version to use

Responses

200

302

Redirects the browser to the carrier login page, with the needed parameters

400

Invalid parameters provided by the user

401

Invalid ShippoToken or unsupported carrier account provided by the user

422

Invalid carrier account provided by the user

GET /carrier_accounts/{CarrierAccountObjectId}/signin/initiate

Carrierparceltemplates 2 endpoints

GET /parcel-templates List all carrier parcel templates

List all carrier parcel template objects.
Use the following query string params to filter the results as needed.
<ul> <li>include=all (the default). Includes templates from all carriers </li> <li>include=user. Includes templates only from carriers which the user has added (whether or not they’re currently enabled) </li> <li>include=enabled. includes templates only for carriers which the user has added and enabled </li> <li>carrier=*token*. filter by specific carrier, e.g. fedex, usps </li> </ul>

operationId: CarrierParcelTemplates_listAllCarrierParcelTemplates

Parameters

Name	In	Required	Type	Description
include	query	optional	string	filter by user or enabled
carrier	query	optional	string	filter by specific carrier
SHIPPO-API-VERSION	header	optional	string	String used to pick a non-default API version to use

Responses

200 —

GET /parcel-templates

GET /parcel-templates/{CarrierParcelTemplateToken} Retrieve a carrier parcel templates

Fetches the parcel template information for a specific carrier parcel template, identified by the token.

operationId: CarrierParcelTemplates_getTemplateById

Parameters

Name	In	Required	Type	Description
CarrierParcelTemplateToken	path	required	string	The unique string representation of the carrier parcel template
SHIPPO-API-VERSION	header	optional	string	String used to pick a non-default API version to use

Responses

200 —

GET /parcel-templates/{CarrierParcelTemplateToken}

Customsdeclarations 3 endpoints

GET /customs/declarations List all customs declarations

Returns a a list of all customs declaration objects

operationId: CustomsDeclarations_listAllDeclarations

Parameters

Name	In	Required	Type	Description
page	query	optional	integer	The page number you want to select
results	query	optional	integer	The number of results to return per page (max 100, default 5)
SHIPPO-API-VERSION	header	optional	string	String used to pick a non-default API version to use

Responses

200 —

GET /customs/declarations

POST /customs/declarations Create a new customs declaration

Creates a new customs declaration object

operationId: CustomsDeclarations_createNewDeclaration

Parameters

Name	In	Required	Type	Description
SHIPPO-API-VERSION	header	optional	string	String used to pick a non-default API version to use

Request Body

CustomsDeclaration details.

application/json

schema CustomsDeclarationCreateRequest

Property	Type	Required
notes	string	optional
aes_itn	string	optional
certify	boolean	required
eel_pfc	string	optional
invoice	string	optional
license	string	optional
incoterm	string	optional
metadata	string	optional
disclaimer	string	optional
b13a_number	string	optional
certificate	string	optional
contents_type	string	required
certify_signer	string	required
is_vat_collected	object	optional
b13a_filing_option	string	optional
commercial_invoice	string	optional
exporter_reference	string	optional
importer_reference	string	optional
non_delivery_option	string	required
contents_explanation	string	optional
…3 more	object	optional

Responses

201 —

POST /customs/declarations

GET /customs/declarations/{CustomsDeclarationId} Retrieve a customs declaration

Returns an existing customs declaration using an object ID

operationId: CustomsDeclarations_getDeclarationById

Parameters

Name	In	Required	Type	Description
CustomsDeclarationId	path	required	string	Object ID of the customs declaration
page	query	optional	integer	The page number you want to select
SHIPPO-API-VERSION	header	optional	string	String used to pick a non-default API version to use

Responses

200 —

GET /customs/declarations/{CustomsDeclarationId}

Customsitems 3 endpoints

GET /customs/items List all customs items

Returns a list all customs items objects.

operationId: CustomsItems_listAllItems

Parameters

Name	In	Required	Type	Description
page	query	optional	integer	The page number you want to select
results	query	optional	integer	The number of results to return per page (max 100)
SHIPPO-API-VERSION	header	optional	string	String used to pick a non-default API version to use

Responses

200 —

GET /customs/items

POST /customs/items Create a new customs item

Creates a new customs item object.

operationId: CustomsItems_createNewCustomsItem

Parameters

Name	In	Required	Type	Description
SHIPPO-API-VERSION	header	optional	string	String used to pick a non-default API version to use

Request Body

CustomsItem details.

application/json

schema CustomsItemBase

Property	Type	Required
metadata	string	optional
quantity	integer	required
sku_code	string	optional
mass_unit	string	required
eccn_ear99	string	optional
net_weight	string	required
description	string	required
value_amount	string	required
tariff_number	string	optional
origin_country	string	required
value_currency	string	required

Responses

201 —

POST /customs/items

GET /customs/items/{CustomsItemId} Retrieve a customs item

Returns an existing customs item using an object ID

operationId: CustomsItems_getExistingItem

Parameters

Name	In	Required	Type	Description
CustomsItemId	path	required	string	Object ID of the customs item
page	query	optional	integer	The page number you want to select
SHIPPO-API-VERSION	header	optional	string	String used to pick a non-default API version to use

Responses

200 —

GET /customs/items/{CustomsItemId}

Manifests 3 endpoints

GET /manifests List all manifests

Returns a list of all manifest objects.

operationId: Manifests_listAllManifests

Parameters

Name	In	Required	Type	Description
page	query	optional	integer	The page number you want to select
results	query	optional	integer	The number of results to return per page (max 100, default 5)
SHIPPO-API-VERSION	header	optional	string	String used to pick a non-default API version to use

Responses

200 —

GET /manifests

POST /manifests Create a new manifest

Creates a new manifest object.

operationId: Manifests_createNewManifest

Parameters

Name	In	Required	Type	Description
SHIPPO-API-VERSION	header	optional	string	String used to pick a non-default API version to use

Request Body

Manifest details and contact info.

application/json

schema ManifestCreateRequest

Property	Type	Required
transactions	array	optional
shipment_date	string	required
carrier_account	string	required
async	boolean	optional
address_from	object	required

Responses

201 —

POST /manifests

GET /manifests/{ManifestId} Retrieve a manifest

Returns an existing manifest using an object ID.

operationId: Manifests_getManifestById

Parameters

Name	In	Required	Type	Description
ManifestId	path	required	string	Object ID of the manifest to update
SHIPPO-API-VERSION	header	optional	string	String used to pick a non-default API version to use

Responses

200 —

GET /manifests/{ManifestId}

Orders 3 endpoints

GET /orders List all orders

Returns a list of all order objects.

operationId: Orders_listAllOrders

Parameters

Name	In	Required	Type	Description
page	query	optional	integer	The page number you want to select
results	query	optional	integer	The number of results to return per page (max 100)
SHIPPO-API-VERSION	header	optional	string	String used to pick a non-default API version to use

Responses

200 —

GET /orders

POST /orders Create a new order

Creates a new order object.

operationId: Orders_createNewOrder

Parameters

Name	In	Required	Type	Description
SHIPPO-API-VERSION	header	optional	string	String used to pick a non-default API version to use

Request Body

Order details.

application/json

schema OrderCreateRequest

Property	Type	Required
notes	string	optional
weight	string	optional
currency	string	optional
placed_at	string	required
total_tax	string	optional
total_price	string	optional
weight_unit	string	optional
order_number	string	optional
order_status	string	optional
shipping_cost	string	optional
subtotal_price	string	optional
shipping_method	string	optional
shipping_cost_currency	string	optional
line_items	array	optional
└ sku	string	optional
└ title	string	optional
└ weight	string	optional
└ currency	string	optional
└ quantity	integer	optional
└ total_price	string	optional
└ weight_unit	string	optional
└ max_ship_time	string	optional
└ variant_title	string	optional
└ max_delivery_time	string	optional
└ manufacture_country	string	optional
to_address	object	required
└ zip	string	optional
└ city	string	optional
└ name	string	optional
└ email	string	optional
└ phone	string	optional
└ state	string	optional
└ company	string	optional
└ country	string	required
└ street1	string	optional
└ street2	string	optional
└ street3	string	optional
└ latitude	number	optional
└ metadata	string	optional
└ longitude	number	optional
└ street_no	string	optional
└ is_residential	boolean	optional
└ validate	boolean	optional
from_address	object	optional
└ zip	string	optional
└ city	string	optional
└ name	string	optional
└ email	string	optional
└ phone	string	optional
└ state	string	optional
└ company	string	optional
└ country	string	required
└ street1	string	optional
└ street2	string	optional
└ street3	string	optional
└ latitude	number	optional
└ metadata	string	optional
└ longitude	number	optional
└ street_no	string	optional
└ is_residential	boolean	optional
└ validate	boolean	optional

Responses

201 —

POST /orders

GET /orders/{OrderId} Retrieve an order

Retrieves an existing order using an object ID.

operationId: Orders_getOrderById

Parameters

Name	In	Required	Type	Description
OrderId	path	required	string	Object ID of the order
SHIPPO-API-VERSION	header	optional	string	String used to pick a non-default API version to use

Responses

200 —

GET /orders/{OrderId}

Parcels 3 endpoints

GET /parcels List all parcels

Returns a list of all parcel objects.

operationId: Parcels_listAll

Parameters

Name	In	Required	Type	Description
page	query	optional	integer	The page number you want to select
results	query	optional	integer	The number of results to return per page (max 100)
SHIPPO-API-VERSION	header	optional	string	String used to pick a non-default API version to use

Responses

200 —

GET /parcels

POST /parcels Create a new parcel

Creates a new parcel object.

operationId: Parcels_createNewParcel

Parameters

Name	In	Required	Type	Description
SHIPPO-API-VERSION	header	optional	string	String used to pick a non-default API version to use

Request Body

Parcel details.

application/json

schema ParcelRequest

Property	Type	Required
test	boolean	optional
extra	object	optional
└ COD	object	optional
└ amount	string	optional
└ currency	string	optional
└ payment_method	string	optional
└ insurance	object	optional
└ amount	string	optional
└ content	string	optional
└ currency	string	optional
└ provider	string	optional
└ reference_1	string	optional
└ reference_2	string	optional
width	string	required
height	string	required
length	string	required
weight	string	required
metadata	string	optional
template	object	optional
mass_unit	string	required
distance_unit	string	required

Responses

201 —

POST /parcels

GET /parcels/{ParcelId} Retrieve an existing parcel

Returns parcel details using an existing parcel object ID (this will not return parcel details associated with un-purchased shipment/rate parcel object IDs).

operationId: Parcels_getParcelDetails

Parameters

Name	In	Required	Type	Description
ParcelId	path	required	string	Object ID of the parcel
SHIPPO-API-VERSION	header	optional	string	String used to pick a non-default API version to use

Responses

200 —

GET /parcels/{ParcelId}

Pickups 1 endpoints

POST /pickups Create a pickup

Creates a pickup object. This request is for a carrier to come to a specified location to take a package for shipping.

operationId: Pickups_createObject

Parameters

Name	In	Required	Type	Description
SHIPPO-API-VERSION	header	optional	string	String used to pick a non-default API version to use

Request Body

Shippo’s pickups endpoint allows you to schedule pickups with USPS and DHL Express for eligible shipments that you have already created.

application/json

schema PickupBase

Property	Type	Required
location	object	required
└ address	object	required
└ zip	string	required
└ city	string	required
└ name	string	required
└ email	string	optional
└ phone	string	optional
└ state	string	required
└ company	string	optional
└ country	string	required
└ street1	string	required
└ street2	string	optional
└ street3	string	optional
└ latitude	number	optional
└ metadata	string	optional
└ longitude	number	optional
└ street_no	string	optional
└ is_residential	boolean	optional
└ validate	boolean	optional
└ instructions	string	optional
└ building_type	string	optional
└ building_location_type	string	required
metadata	string	optional
transactions	array	required
carrier_account	string	required
requested_end_time	string	required
requested_start_time	string	required

Responses

201 —

POST /pickups

Rates 3 endpoints

GET /rates/{RateId} Retrieve a rate

Returns an existing rate using a rate object ID.

operationId: Rates_getRateById

Parameters

Name	In	Required	Type	Description
RateId	path	required	string	Object ID of the rate
SHIPPO-API-VERSION	header	optional	string	String used to pick a non-default API version to use

Responses

200 —

GET /rates/{RateId}

GET /shipments/{ShipmentId}/rates Retrieve shipment rates

Returns a paginated list of rates associated with a shipment

operationId: Rates_getShipmentRates

Parameters

Name	In	Required	Type	Description
ShipmentId	path	required	string	Object ID of the shipment to update
page	query	optional	integer	The page number you want to select
results	query	optional	integer	The number of results to return per page (max 100)
SHIPPO-API-VERSION	header	optional	string	String used to pick a non-default API version to use

Responses

200 —

GET /shipments/{ShipmentId}/rates

GET /shipments/{ShipmentId}/rates/{CurrencyCode} Retrieve shipment rates in currency

Returns all available shipping rates for a shipment object.

When you create a new valid shipment object, Shippo automatically calculates all available rates. Depending on your shipment data, there may be none, one or multiple rates.

By default, the calculated rates will return the price in two currencies under the amount and amount_local keys, respectively. The amount key will contain the price of a rate expressed in the currency that is used in the country from where the parcel originates, and the amount_local key will contain the price expressed in the currency that is used in the country the parcel is shipped to. You can request rates with prices expressed in a different currency by adding the currency code to the end of the resource URL. The full list of supported currencies along with their codes can be viewed on open exchange rates.

Note: re-requesting the rates with a different currency code will re-queue the shipment (i.e. set the Shipment’s status to QUEUED) and the converted currency rates will only be available when the Shipment’s status is set to SUCCESS.

operationId: Rates_getShipmentRatesInCurrency

Parameters

Name	In	Required	Type	Description
ShipmentId	path	required	string	Object ID of the shipment to update
CurrencyCode	path	required	string	ISO currency code for the rates
page	query	optional	integer	The page number you want to select
results	query	optional	integer	The number of results to return per page (max 100)
SHIPPO-API-VERSION	header	optional	string	String used to pick a non-default API version to use

Responses

200 —

GET /shipments/{ShipmentId}/rates/{CurrencyCode}

Ratesatcheckout 4 endpoints

POST /live-rates Generate a live rates request

Initiates a live rates request. Include either the object ID for
an existing address record or a fully formed address object when entering
an address value. You can also enter the object ID of an existing user parcel
template or a fully formed user parcel template object as the parcel value.

operationId: RatesAtCheckout_initiateLiveRatesRequest

Parameters

Name	In	Required	Type	Description
SHIPPO-API-VERSION	header	optional	string	String used to pick a non-default API version to use

Request Body

Generate rates at checkout

application/json

schema LiveRateCreateRequest

Property	Type	Required
parcel	object	optional
address_to	object	required
line_items	array	required
└ sku	string	optional
└ title	string	optional
└ weight	string	optional
└ currency	string	optional
└ quantity	integer	optional
└ total_price	string	optional
└ weight_unit	string	optional
└ max_ship_time	string	optional
└ variant_title	string	optional
└ max_delivery_time	string	optional
└ manufacture_country	string	optional
└ object_id	string	optional
address_from	object	optional

Responses

200 —

POST /live-rates

DELETE /live-rates/settings/parcel-template Clear current default parcel template

Clears the currently configured default parcel template for live rates.

operationId: RatesAtCheckout_clearDefaultParcelTemplate

Parameters

Name	In	Required	Type	Description
SHIPPO-API-VERSION	header	optional	string	String used to pick a non-default API version to use

Responses

204

The parcel template was successfully deleted.

DELETE /live-rates/settings/parcel-template

GET /live-rates/settings/parcel-template Show current default parcel template

Retrieve and display the currently configured default parcel template for live rates.

operationId: RatesAtCheckout_showDefaultParcelTemplate

Parameters

Name	In	Required	Type	Description
SHIPPO-API-VERSION	header	optional	string	String used to pick a non-default API version to use

Responses

200 —

GET /live-rates/settings/parcel-template

PUT /live-rates/settings/parcel-template Update default parcel template

Update the currently configured default parcel template for live rates. The object_id in the request payload should identify the user parcel template to be the new default.

operationId: RatesAtCheckout_updateDefaultParcelTemplate

Parameters

Name	In	Required	Type	Description
SHIPPO-API-VERSION	header	optional	string	String used to pick a non-default API version to use

Request Body

application/json

schema DefaultParcelTemplateUpdateRequest

Property	Type	Required
object_id	string	optional

Responses

200 —

PUT /live-rates/settings/parcel-template

Refunds 2 endpoints

GET /refunds List all refunds

Returns a list all refund objects.

operationId: Refunds_listAll

Parameters

Name	In	Required	Type	Description
SHIPPO-API-VERSION	header	optional	string	String used to pick a non-default API version to use

Responses

200 —

GET /refunds

GET /refunds/{RefundId} Retrieve a refund

Returns an existing rate using a rate object ID.

operationId: Refunds_getRefundById

Parameters

Name	In	Required	Type	Description
RefundId	path	required	string	Object ID of the refund to update
SHIPPO-API-VERSION	header	optional	string	String used to pick a non-default API version to use

Responses

200 —

GET /refunds/{RefundId}

Servicegroups 4 endpoints

GET /service-groups List all service groups

Returns a list of service group objects.

operationId: ServiceGroups_listAllServiceGroups

Parameters

Name	In	Required	Type	Description
SHIPPO-API-VERSION	header	optional	string	String used to pick a non-default API version to use

Responses

200 —

GET /service-groups

POST /service-groups Create a new service group

Creates a new service group.

operationId: ServiceGroups_createNewGroup

Parameters

Name	In	Required	Type	Description
SHIPPO-API-VERSION	header	optional	string	String used to pick a non-default API version to use

Request Body

application/json

schema ServiceGroupCreateRequest

Property	Type	Required
name	string	required
type	string	required
flat_rate	string	optional
description	string	required
rate_adjustment	integer	optional
flat_rate_currency	string	optional
free_shipping_threshold_min	string	optional
free_shipping_threshold_currency	string	optional
service_levels	array	required
└ account_object_id	string	optional
└ service_level_token	string	optional

Responses

201 —

POST /service-groups

PUT /service-groups Update an existing service group

Updates an existing service group object.
The object_id cannot be updated as it is the unique identifier for the object.

operationId: ServiceGroups_updateExistingGroup

Parameters

Name	In	Required	Type	Description
SHIPPO-API-VERSION	header	optional	string	String used to pick a non-default API version to use

Request Body

application/json

schema ServiceGroupUpdateRequest

Property	Type	Required
name	string	required
type	string	required
flat_rate	string	optional
description	string	required
rate_adjustment	integer	optional
flat_rate_currency	string	optional
free_shipping_threshold_min	string	optional
free_shipping_threshold_currency	string	optional
is_active	boolean	required
object_id	string	required
service_levels	array	required
└ account_object_id	string	optional
└ service_level_token	string	optional

Responses

200 —

PUT /service-groups

DELETE /service-groups/{ServiceGroupId} Delete a service group

Deletes an existing service group using an object ID.

operationId: ServiceGroups_deleteServiceGroup

Parameters

Name	In	Required	Type	Description
ServiceGroupId	path	required	string	Object ID of the service group
SHIPPO-API-VERSION	header	optional	string	String used to pick a non-default API version to use

Responses

204

The service group was successfully deleted.

DELETE /service-groups/{ServiceGroupId}

Shipments 3 endpoints

GET /shipments List all shipments

Returns a list of all shipment objects.

In order to filter results, you must use the below path parameters.
A maximum date range of 90 days is permitted.
Provided dates should be ISO 8601 UTC dates (timezone offsets are currently not supported).

Optional path parameters:

object_created_gt- object(s) created greater than a provided date time

object_created_gte - object(s) created greater than or equal to a provided date time

object_created_lt - object(s) created less than a provided date time

object_created_lte - object(s) created less than or equal to a provided date time

Date format examples:

2017-01-01

2017-01-01T03:30:30 or 2017-01-01T03:30:30.5

2017-01-01T03:30:30Z

Example URL:

https://api.goshippo.com/shipments/?object_created_gte=2017-01-01T00:00:30&object_created_lt=2017-04-01T00:00:30

operationId: Shipments_listAllShipments

Parameters

Name	In	Required	Type	Description
page	query	optional	integer	The page number you want to select
results	query	optional	integer	The number of results to return per page (max 100)
SHIPPO-API-VERSION	header	optional	string	String used to pick a non-default API version to use

Responses

200 —

GET /shipments

POST /shipments Create a new shipment

Creates a new shipment object.

operationId: Shipments_createNewShipment

Parameters

Name	In	Required	Type	Description
SHIPPO-API-VERSION	header	optional	string	String used to pick a non-default API version to use

Request Body

Shipment details and contact info.

application/json

schema ShipmentCreateRequest

Property	Type	Required
extra	object	optional
└ COD	object	optional
└ amount	string	optional
└ currency	string	optional
└ payment_method	string	optional
└ alcohol	object	optional
└ recipient_type	string	optional
└ contains_alcohol	boolean	optional
└ billing	object	optional
└ zip	string	optional
└ type	string	optional
└ account	string	optional
└ country	string	optional
└ participation_code	string	optional
└ dry_ice	object	optional
└ weight	string	optional
└ contains_dry_ice	boolean	optional
└ premium	boolean	optional
└ insurance	object	optional
└ amount	string	optional
└ content	string	optional
└ currency	string	optional
└ provider	string	optional
└ is_return	boolean	optional
└ po_number	object	optional
└ value	string	optional
└ prefix	string	optional
└ rma_number	object	optional
└ value	string	optional
└ prefix	string	optional
└ dept_number	object	optional
└ value	string	optional
└ prefix	string	optional
└ reference_1	string	optional
└ reference_2	string	optional
└ carbon_neutral	boolean	optional
└ carrier_hub_id	string	optional
└ container_type	string	optional
└ invoice_number	object	optional
└ value	string	optional
└ prefix	string	optional
└ customer_branch	string	optional
└ dangerous_goods	object	optional
└ contains	boolean	optional
└ lithium_batteries	object	optional
└ contains	boolean	optional
└ biological_material	object	optional
└ contains	boolean	optional
└ lasership_attrs	string	optional
└ qr_code_requested	boolean	optional
└ …15 more	object	optional
metadata	string	optional
shipment_date	string	optional
customs_declaration	string	optional
async	boolean	optional
parcels	array	required
address_to	object	required
address_from	object	required
address_return	object	optional
carrier_accounts	array	optional

Responses

201 —

POST /shipments

GET /shipments/{ShipmentId} Retrieve a shipment

Returns an existing shipment using an object ID

operationId: Shipments_getShipmentById

Parameters

Name	In	Required	Type	Description
ShipmentId	path	required	string	Object ID of the shipment to update
SHIPPO-API-VERSION	header	optional	string	String used to pick a non-default API version to use

Responses

200 —

GET /shipments/{ShipmentId}

Load more endpoints

Schemas

object Address

{
  "allOf": [
    {
      "$ref": "#/components/schemas/AddressBase"
    },
    {
      "required": [
        "country"
      ],
      "properties": {
        "test": {
          "type": "boolean",
          "example": false,
          "description": "Indicates whether the object has been created in test mode."
        },
        "object_id": {
          "type": "string",
          "example": "d799c2679e644279b59fe661ac8fa488",
          "description": "Unique identifier of the given Address object. \nThis ID is required to create a Shipment object."
        },
        "is_complete": {
          "type": "boolean",
          "example": true,
          "description": "Complete addresses contain all required values.<br><br>Incomplete addresses have failed one or multiple \nvalidations.<br>Incomplete Addresses are eligible for requesting rates but lack at least one required \nvalue for purchasing labels."
        },
        "object_owner": {
          "type": "string",
          "example": "shippotle@shippo.com",
          "description": "Username of the user who created the Address object."
        },
        "object_created": {
          "type": "string",
          "format": "date-time",
          "example": "2014-07-09T02:19:13.174Z",
          "description": "Date and time of Address creation."
        },
        "object_updated": {
          "type": "string",
          "format": "date-time",
          "example": "2014-07-09T02:19:13.174Z",
          "description": "Date and time of last Address update. Since you cannot update Addresses after they were created, this time \nstamp reflects the time when the Address was changed by Shippo's systems for the last time, e.g., during the \napproximation of one or more values."
        },
        "validation_results": {
          "$ref": "#/components/schemas/AddressValidationResults"
        }
      }
    }
  ]
}

object AddressBase

{
  "type": "object",
  "properties": {
    "zip": {
      "type": "string",
      "example": "94117",
      "description": "**required for purchase**<br>\nPostal code of an Address. When creating a Quote Addresses, sending a ZIP is optional but will yield more \naccurate Rates."
    },
    "city": {
      "type": "string",
      "example": "San Francisco",
      "description": "**required for purchase**<br>\nName of a city. When creating a Quote Address, sending a city is optional but will yield more accurate Rates. \nPlease bear in mind that city names may be ambiguous (there are 34 Springfields in the US). Pass in a state \nor a ZIP code (see below), if known, it will yield more accurate results."
    },
    "name": {
      "type": "string",
      "example": "Shwan Ippotle",
      "description": "**required for purchase**<br>\nFirst and Last Name of the addressee"
    },
    "email": {
      "type": "string",
      "example": "shippotle@shippo.com",
      "description": "E-mail address of the contact person, RFC3696/5321-compliant."
    },
    "phone": {
      "type": "string",
      "example": "+1 555 341 9393",
      "description": "Addresses containing a phone number allow carriers to call the recipient when delivering the Parcel. This \nincreases the probability of delivery and helps to avoid accessorial charges after a Parcel has been shipped.    "
    },
    "state": {
      "type": "string",
      "example": "CA",
      "description": "**required for purchase for some countries**<br>\nState/Province values are required for shipments from/to the US, AU, and CA. UPS requires province for some \ncountries (i.e Ireland). To receive more accurate quotes, passing this field is recommended. Most carriers \nonly accept two or three character state abbreviations."
    },
    "company": {
      "type": "string",
      "example": "Shippo",
      "description": "Company Name"
    },
    "country": {
      "type": "string",
      "example": "US",
      "description": "Example: `US` or `DE`. All accepted values can be found on the \n<a href=\"http://www.iso.org/\" target=\"blank\">Official ISO Website</a>.\nSending a country is always required."
    },
    "street1": {
      "type": "string",
      "example": "215 Clayton St.",
      "description": "**required for purchase**<br>\nFirst street line, 35 character limit. Usually street number and street name (except for DHL Germany, see street_no)."
    },
    "street2": {
      "type": "string",
      "description": "Second street line, 35 character limit."
    },
    "street3": {
      "type": "string",
      "example": "",
      "description": "Third street line, 35 character limit. \nOnly accepted for USPS international shipments, UPS domestic and UPS international shipments."
    },
    "latitude": {
      "type": "number",
      "description": "Latitude of address"
    },
    "metadata": {
      "type": "string",
      "example": "Customer ID 123456",
      "description": "A string of up to 100 characters that can be filled with any additional information you want \nto attach to the object."
    },
    "longitude": {
      "type": "number",
      "description": "Longitude of address"
    },
    "street_no": {
      "type": "string",
      "example": "",
      "description": "Street number of the addressed building. \nThis field can be included in street1 for all carriers except for DHL Germany."
    },
    "is_residential": {
      "type": "boolean",
      "example": true
    }
  },
  "description": "Address represents the address as retrieved from the database"
}

object AddressCompleteCreateRequest

{
  "allOf": [
    {
      "$ref": "#/components/schemas/AddressBase"
    },
    {
      "required": [
        "name",
        "street1",
        "city",
        "state",
        "zip",
        "country"
      ],
      "properties": {
        "validate": {
          "type": "boolean",
          "example": true
        }
      }
    }
  ]
}

object AddressCreateRequest

{
  "allOf": [
    {
      "$ref": "#/components/schemas/AddressBase"
    },
    {
      "required": [
        "country"
      ],
      "properties": {
        "validate": {
          "type": "boolean",
          "example": true,
          "description": "Set to true to validate Address object."
        }
      }
    }
  ]
}

object AddressImporter

{
  "type": "object",
  "properties": {
    "zip": {
      "type": "string",
      "example": "80331",
      "description": "Postal code of an Address."
    },
    "city": {
      "type": "string",
      "example": "München",
      "description": "Name of a city"
    },
    "name": {
      "type": "string",
      "example": "Shwan Ippotle",
      "description": "First and Last Name of the addressee"
    },
    "email": {
      "type": "string",
      "example": "shippotle@shippo.com",
      "description": "E-mail address of the contact person, RFC3696/5321-compliant."
    },
    "phone": {
      "type": "string",
      "example": "80331",
      "description": "Addresses containing a phone number allow carriers to call the recipient when delivering the Parcel. This \nincreases the probability of delivery and helps to avoid accessorial charges after a Parcel has been shipped.    "
    },
    "state": {
      "type": "string",
      "example": "CA",
      "description": "**required for purchase for some countries**<br>\nState/Province values are required for shipments from/to the US, AU, and CA. UPS requires province for some \ncountries (i.e Ireland). To receive more accurate quotes, passing this field is recommended. Most carriers \nonly accept two or three character state abbreviations."
    },
    "company": {
      "type": "string",
      "example": "Shippo",
      "description": "Company Name"
    },
    "country": {
      "type": "string",
      "example": "DE",
      "description": "Example: `US` or `DE`. All accepted values can be found on the \n<a href=\"http://www.iso.org/\" target=\"blank\">Official ISO Website</a>.\nSending a country is always required."
    },
    "street1": {
      "type": "string",
      "example": "Blumenstraße",
      "description": "First street line, 35 character limit. Usually street number and street name (except for DHL Germany, see street_no)."
    },
    "street2": {
      "type": "string",
      "description": "Second street line, 35 character limit."
    },
    "street3": {
      "type": "string",
      "example": "",
      "description": "Third street line, 35 character limit. \nOnly accepted for USPS international shipments, UPS domestic and UPS international shipments."
    },
    "street_no": {
      "type": "string",
      "example": "22",
      "description": "Street number of the addressed building. \nThis field can be included in street1 for all carriers except for DHL Germany."
    },
    "is_residential": {
      "type": "boolean",
      "example": true,
      "description": "Indicates whether the address provided is a residential address or not."
    }
  },
  "description": "Object that represents the address of the importer"
}

object AddressImporterResponse

{
  "properties": {
    "object_id": {
      "type": "string",
      "example": "7506ccbb65a34a8a9ac2cc4a89e820d2",
      "description": "ID of importer address object"
    }
  }
}

object AddressPaginatedList

{
  "allOf": [
    {
      "$ref": "#/components/schemas/PaginatedList"
    },
    {
      "properties": {
        "results": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/Address"
          }
        }
      }
    }
  ]
}

object AddressValidationResults

{
  "type": "object",
  "properties": {
    "is_valid": {
      "type": "boolean",
      "example": false
    },
    "messages": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/AddressValidationResultsMessage"
      }
    }
  },
  "description": "Object that contains information regarding if an address had been validated or not. Also contains any messages \ngenerated during validation. Children keys are <code>is_valid</code>(boolean) and <code>messages</code>(array)."
}

object AddressValidationResultsMessage

{
  "type": "object",
  "properties": {
    "code": {
      "enum": [
        "verification_error",
        "unknown_street",
        "component_mismatch_error",
        "multiple_match",
        "sub_premise_number_invalid",
        "sub_premise_number_missing",
        "premise_number_invalid",
        "premise_number_missing",
        "box_number_invalid",
        "box_number_missing",
        "pmb_number_missing",
        "postal_code_change",
        "administrative_area_change",
        "locality_change",
        "dependent_locality_change",
        "street_name_change",
        "street_type_change",
        "street_directional_change",
        "sub_premise_type_change",
        "sub_premise_number_change",
        "double_dependent_locality_change",
        "subadministrative_area_change",
        "subnational_area_change",
        "po_box_change",
        "premise_type_change",
        "house_number_change",
        "organization_change",
        "extraneous_information",
        "usps_door_inaccessible",
        "administrative_area_partial",
        "city_partial",
        "street_partial",
        "building_partial",
        "subpremise_partial",
        "administrative_area_full",
        "city_full",
        "thoroughfare_full",
        "premises_full",
        "subpremise_full",
        "geocoded_street",
        "geocoded_neighborhood",
        "geocoded_community",
        "geocoded_state",
        "geocoded_rooftop",
        "geocoded_interpolated_rooftop",
        "invalid_postal_code",
        "postal_code_not_found",
        "empty_request",
        "service_error",
        "street_detail_missing",
        "Invalid City/State/Zip",
        "Default Match",
        "Unknown Street",
        "Address Not Found",
        "Non-Deliverable ZIP4",
        "Multiple Responses",
        "Invalid Dual Address",
        "Invalid State",
        "Invalid City",
        "Ambiguous Address"
      ],
      "type": "string",
      "example": "Unknown Street"
    },
    "text": {
      "type": "string",
      "example": "City, State and ZIP Code are valid, but street address is not a match."
    },
    "type": {
      "type": "string",
      "example": "address_warning"
    },
    "source": {
      "enum": [
        "Shippo Address Validator",
        "UPS"
      ],
      "type": "string",
      "example": "Shippo Address Validator"
    }
  }
}

object Alcohol

{
  "type": "object",
  "properties": {
    "recipient_type": {
      "enum": [
        "licensee",
        "consumer"
      ],
      "type": "string",
      "description": "Mandatory for Fedex only. License type of the recipient of the Alcohol Package."
    },
    "contains_alcohol": {
      "type": "boolean",
      "description": "Mandatory for Fedex and UPS. Specifies that the package contains Alcohol."
    }
  },
  "description": "Indicates that a shipment contains Alcohol (Fedex and UPS only)."
}

object AmountAndCurrencyCharged

{
  "type": "object",
  "properties": {
    "amount": {
      "type": "string",
      "example": "5.52",
      "description": "The money amount"
    },
    "currency": {
      "type": "string",
      "example": "USD",
      "description": "The currency that 'amount' is in. The official ISO 4217 currency codes are used, e.g. \"USD\" or \"EUR\".\n<a href=\"http://www.xe.com/iso4217.php\" target=\"blank\">ISO 4217 Standard</a>."
    }
  },
  "description": "The amount and currency that was charged after possible currency conversion occurred."
}

object AmountAndCurrencyInvoiced

{
  "type": "object",
  "properties": {
    "amount": {
      "type": "string",
      "example": "5.52",
      "description": "The money amount"
    },
    "currency": {
      "type": "string",
      "example": "USD",
      "description": "The currency that 'amount' is in. The official ISO 4217 currency codes are used, e.g. \"USD\" or \"EUR\".\n<a href=\"http://www.xe.com/iso4217.php\" target=\"blank\">ISO 4217 Standard</a>."
    }
  },
  "description": "The amount and currency."
}

object BadRequestWithDetail

{
  "type": "object",
  "properties": {
    "detail": {
      "type": "string",
      "example": "Your registration unfortunately failed due to the following UPS error: Missing or invalid ControlID."
    }
  }
}

object BadRequestWithError

{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "example": "Only US shippers can create a new USPS account"
    }
  }
}

object Batch

{
  "allOf": [
    {
      "$ref": "#/components/schemas/BatchBase"
    },
    {
      "required": [
        "object_id",
        "object_owner",
        "status",
        "object_created",
        "object_updated",
        "batch_shipments",
        "object_results",
        "label_url"
      ],
      "properties": {
        "test": {
          "type": "boolean",
          "example": false
        },
        "status": {
          "enum": [
            "VALIDATING",
            "VALID",
            "INVALID",
            "PURCHASING",
            "PURCHASED"
          ],
          "type": "string",
          "example": "VALID",
          "description": "Batches that are `VALIDATING` are being created and validated<br>\n`VALID` batches can be purchased<br>\n`INVALID` batches cannot be purchased, `INVALID` BatchShipments must be removed<br>\nBatches that are in the `PURCHASING` state are being purchased<br>\n`PURCHASED` batches are finished purchasing."
        },
        "label_url": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "An array of URLs each pointing to a merged file of 100 labels each"
        },
        "object_id": {
          "type": "string",
          "example": "5ef63c54f5bf45d3b1f8fb37dcb1c5f4",
          "description": "Unique identifier of the given Batch object"
        },
        "object_owner": {
          "type": "string",
          "example": "shippo@shippo.com",
          "description": "Username of the user who created the Address object."
        },
        "object_created": {
          "type": "string",
          "example": "2016-01-04T00:15:44.394Z",
          "description": "Date and time of Batch creation"
        },
        "object_results": {
          "type": "object",
          "required": [
            "purchase_failed",
            "purchase_succeeded",
            "creation_failed",
            "creation_succeeded"
          ],
          "properties": {
            "creation_failed": {
              "type": "integer",
              "format": "int64",
              "example": 3
            },
            "purchase_failed": {
              "type": "integer",
              "format": "int64",
              "example": 0
            },
            "creation_succeeded": {
              "type": "integer",
              "format": "int64",
              "example": 5
            },
            "purchase_succeeded": {
              "type": "integer",
              "format": "int64",
              "example": 0
            }
          },
          "description": "An object containing the following counts:<br>`creation_succeeded`<br>`creation_failed`<br>`purchase_succeeded`<br>`purchase_failed`"
        },
        "object_updated": {
          "type": "string",
          "example": "2016-01-04T00:48:13.841Z",
          "description": "Date and time of last update to the Batch"
        },
        "batch_shipments": {
          "$ref": "#/components/schemas/BatchShipmentPaginatedList"
        }
      }
    }
  ]
}

object BatchBase

{
  "type": "object",
  "required": [
    "default_carrier_account",
    "default_servicelevel_token"
  ],
  "properties": {
    "metadata": {
      "type": "string",
      "example": "BATCH #1",
      "maxLength": 100,
      "description": "A string of up to 100 characters that can be filled with any additional information you want to attach to the object."
    },
    "label_filetype": {
      "$ref": "#/components/schemas/LabelFileTypeEnum"
    },
    "default_carrier_account": {
      "type": "string",
      "example": "078870331023437cb917f5187429b093",
      "description": "ID of the Carrier Account object to use as the default for all shipments in this Batch. \nThe carrier account can be changed on a per-shipment basis by changing the carrier_account in the \ncorresponding BatchShipment object."
    },
    "default_servicelevel_token": {
      "type": "string",
      "example": "usps_priority",
      "description": "Token of the service level to use as the default for all shipments in this Batch. \nThe servicelevel can be changed on a per-shipment basis by changing the servicelevel_token in the \ncorresponding BatchShipment object. <a href=\"#tag/Service-Levels\">Servicelevel tokens can be found here.</a>"
    }
  }
}

object BatchCreateRequest

{
  "allOf": [
    {
      "$ref": "#/components/schemas/BatchBase"
    },
    {
      "required": [
        "batch_shipments"
      ],
      "properties": {
        "batch_shipments": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/BatchShipmentBase"
          },
          "description": "Array of BatchShipment objects. The response keeps the same order as in the request array."
        }
      }
    }
  ]
}

object BatchShipment

{
  "allOf": [
    {
      "$ref": "#/components/schemas/BatchShipmentBase"
    },
    {
      "required": [
        "shipment",
        "object_id",
        "status"
      ],
      "properties": {
        "status": {
          "enum": [
            "INVALID",
            "VALID",
            "INCOMPLETE",
            "TRANSACTION_FAILED"
          ],
          "type": "string",
          "example": "INVALID",
          "description": "`INVALID` batch shipments cannot be purchased and will have to be removed, fixed, and added to the batch again.<br>\n`VALID` batch shipments can be purchased. <br>\nBatch shipments with the status `TRANSACTION_FAILED` were not able to be purchased and the error will be displayed on the message field<br> \n`INCOMPLETE` batch shipments have an issue with the Address and will need to be removed, fixed, and added to the batch again."
        },
        "messages": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/ErrorMessage"
          },
          "description": "List of Shipment and Transaction error messages."
        },
        "object_id": {
          "type": "string",
          "example": "e11c95a6788d4ddcaa22f03175838740",
          "description": "Object ID of this batch shipment. Can be used in the remove_shipments endpoint."
        },
        "transaction": {
          "type": "string",
          "example": "4c33736a67e2450da88b38c42deef6b7",
          "description": "Object ID of the transaction object created for this batch shipment."
        }
      }
    }
  ]
}

object BatchShipmentBase

{
  "type": "object",
  "required": [
    "shipment"
  ],
  "properties": {
    "metadata": {
      "type": "string",
      "example": "SHIPMENT #1",
      "maxLength": 100,
      "description": "A string of up to 100 characters that can be filled with any additional information you want \nto attach to the object."
    },
    "shipment": {
      "$ref": "#/components/schemas/ShipmentCreateRequest"
    },
    "carrier_account": {
      "type": "string",
      "example": "a4391cd4ab974f478f55dc08b5c8e3b3",
      "description": "Object ID of the carrier account to be used for this shipment (will override batch default)"
    },
    "servicelevel_token": {
      "type": "string",
      "example": "fedex_ground",
      "description": "A token that sets the shipping method for the batch, overriding the batch default. \nServicelevel tokens can be found <a href=\"#tag/Service-Levels\">in this list</a> \nor <a href=\"#operation/ListCarrierAccounts\">at this endpoint</a>."
    }
  }
}

object BatchShipmentPaginatedList

{
  "allOf": [
    {
      "$ref": "#/components/schemas/PaginatedList"
    },
    {
      "properties": {
        "results": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/BatchShipment"
          }
        }
      },
      "description": "Array of <a href=\"#section/Batch-Shipment\">BatchShipment</a> objects. \nThe response keeps the same order as in the request array."
    }
  ]
}

array BatchesAddShipmentsToBatchRequest

{
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/BatchShipmentBase"
  }
}

array BatchesRemoveShipmentsRequest

{
  "type": "array",
  "items": {
    "type": "string"
  }
}

object Billing

{
  "type": "object",
  "properties": {
    "zip": {
      "type": "string",
      "description": "ZIP code of account number to be billed (required for UPS if there is a zip on the billing account)."
    },
    "type": {
      "enum": [
        "SENDER",
        "RECIPIENT",
        "THIRD_PARTY",
        "THIRD_PARTY_CONSIGNEE",
        "COLLECT"
      ],
      "type": "string",
      "description": "Party to be billed. (Leave blank for DHL Germany.)"
    },
    "account": {
      "type": "string",
      "description": "Account number to be billed. (For DHL Germany, leave this field blank.)"
    },
    "country": {
      "type": "string",
      "format": "iso-3166",
      "description": "Country iso2 code of account number to be billed (required for UPS third party billing only)."
    },
    "participation_code": {
      "type": "string",
      "description": "2 digit code used to override your default participation code associated with your DHL Germany account."
    }
  },
  "description": "Specify billing details (UPS, FedEx, and DHL Germany only)."
}

object COD

{
  "type": "object",
  "title": "COD Specify collection on delivery details (UPS only).",
  "properties": {
    "amount": {
      "type": "string",
      "example": "5.5",
      "description": "Amount to be collected."
    },
    "currency": {
      "type": "string",
      "example": "USD",
      "description": "Currency for the amount to be collected. Currently only USD is supported for UPS."
    },
    "payment_method": {
      "enum": [
        "SECURED_FUNDS",
        "CASH",
        "ANY"
      ],
      "type": "string",
      "example": "CASH",
      "description": "Secured funds include money orders, certified cheques and others (see \n<a href=\"https://www.ups.com/content/us/en/shipping/time/service/value_added/cod.html\">UPS</a> for details). \nIf no payment_method inputted the value defaults to \"ANY\".)"
    }
  },
  "description": "Specify collection on delivery details (UPS only)."
}

object CarrierAccount

{
  "allOf": [
    {
      "$ref": "#/components/schemas/CarrierAccountBase"
    },
    {
      "properties": {
        "test": {
          "type": "boolean",
          "example": false,
          "description": "Indicates whether the object has been created in test mode."
        },
        "metadata": {
          "type": "string"
        },
        "object_id": {
          "type": "string",
          "example": "6aa34d5f6865448fbb1ee93636e98999",
          "description": "Unique identifier of the carrier account object."
        },
        "carrier_name": {
          "example": "USPS",
          "description": "Carrier name, see <a href=\"#tag/Carriers\">Carriers</a><br>"
        },
        "object_owner": {
          "type": "string",
          "example": "bob+22@gmail.com",
          "description": "Username of the user who created the carrier account object."
        },
        "service_levels": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/CarrierAccountServiceLevel"
          }
        },
        "is_shippo_account": {
          "type": "boolean",
          "example": false
        }
      }
    }
  ]
}

object CarrierAccountBase

{
  "type": "object",
  "required": [
    "carrier",
    "account_id"
  ],
  "properties": {
    "active": {
      "type": "boolean",
      "description": "Determines whether the account is active. When creating a shipment, if no `carrier_accounts` are explicitly \npassed Shippo will query all carrier accounts that have this field set. By default, this is set to True."
    },
    "carrier": {
      "type": "string",
      "example": "usps",
      "description": "Carrier token, see <a href=\"#tag/Carriers\">Carriers</a><br>\nPlease check the <a href=\"https://docs.goshippo.com/docs/carriers/carrieraccounts/\">carrier accounts tutorial</a> page for all supported carriers."
    },
    "account_id": {
      "type": "string",
      "example": "****",
      "description": "Unique identifier of the account. Please check the <a href=\"https://docs.goshippo.com/docs/carriers/carrieraccounts/\">carrier accounts tutorial</a> \npage for the `account_id` per carrier.<br> \nTo protect account information, this field will be masked in any API response."
    },
    "parameters": {
      "oneOf": [
        {
          "$ref": "#/components/schemas/ConnectExistingOwnAccountParameters"
        },
        {
          "$ref": "#/components/schemas/UPSConnectExistingOwnAccountParameters"
        }
      ]
    }
  }
}

object CarrierAccountCanadaPostCreateParameters

{
  "type": "object",
  "required": [
    "company",
    "phone",
    "full_name",
    "email",
    "canada_post_terms"
  ],
  "properties": {
    "email": {
      "type": "string",
      "example": "hippo@shippo.com"
    },
    "phone": {
      "type": "string",
      "example": "1112223333",
      "description": "Needs to be a valid phone number and cannot be null"
    },
    "company": {
      "type": "string",
      "example": "Shippo"
    },
    "full_name": {
      "type": "string",
      "example": "Shippo Meister"
    },
    "canada_post_terms": {
      "type": "boolean",
      "description": "Whether or not the user agrees to Canada Post's terms. If passed in as false, request will fail with error 400"
    }
  }
}

object CarrierAccountCanadaPostCreateRequest

{
  "type": "object",
  "title": "Shippo Canada Post account",
  "required": [
    "carrier",
    "parameters"
  ],
  "properties": {
    "carrier": {
      "type": "string",
      "example": "canada_post"
    },
    "parameters": {
      "$ref": "#/components/schemas/CarrierAccountCanadaPostCreateParameters"
    }
  }
}

object CarrierAccountChronopostCreateRequest

{
  "type": "object",
  "title": "Shippo Chronopost account",
  "required": [
    "carrier",
    "parameters"
  ],
  "properties": {
    "carrier": {
      "type": "string",
      "example": "chronopost"
    },
    "parameters": {
      "type": "object"
    }
  }
}

object CarrierAccountColissimoCreateRequest

{
  "type": "object",
  "title": "Shippo Colissimo account",
  "required": [
    "carrier",
    "parameters"
  ],
  "properties": {
    "carrier": {
      "type": "string",
      "example": "colissimo"
    },
    "parameters": {
      "type": "object"
    }
  }
}

object CarrierAccountCorreosCreateRequest

{
  "type": "object",
  "title": "Shippo Correos account",
  "required": [
    "carrier",
    "parameters"
  ],
  "properties": {
    "carrier": {
      "type": "string",
      "example": "correos"
    },
    "parameters": {
      "type": "object"
    }
  }
}

object CarrierAccountDHLExpressCreateRequest

{
  "type": "object",
  "title": "Shippo DHL Express account",
  "required": [
    "carrier",
    "parameters"
  ],
  "properties": {
    "carrier": {
      "type": "string",
      "example": "dhl_express"
    },
    "parameters": {
      "$ref": "#/components/schemas/CarrierAccountDHLExpressCreateRequestParameters"
    }
  }
}

object CarrierAccountDHLExpressCreateRequestParameters

{
  "type": "object",
  "required": [
    "user_accepted_terms_and_conditions"
  ],
  "properties": {
    "user_accepted_terms_and_conditions": {
      "type": "boolean",
      "description": "Whether or not the user agrees to the DHL Express Terms and Conditions. If passed in as false, request will fail with error 400"
    }
  }
}

object CarrierAccountDPDUKCreateRequest

{
  "type": "object",
  "title": "Shippo DPD UK account",
  "required": [
    "carrier",
    "parameters"
  ],
  "properties": {
    "carrier": {
      "type": "string",
      "example": "dpd_uk"
    },
    "parameters": {
      "type": "object"
    }
  }
}

object CarrierAccountDeutschePostCreateRequest

{
  "type": "object",
  "title": "Shippo Deutsche Post account",
  "required": [
    "carrier",
    "parameters"
  ],
  "properties": {
    "carrier": {
      "type": "string",
      "example": "deustche_post"
    },
    "parameters": {
      "type": "object"
    }
  }
}

object CarrierAccountDpdDeCreateRequest

{
  "type": "object",
  "title": "Shippo DPD DE account",
  "required": [
    "carrier",
    "parameters"
  ],
  "properties": {
    "carrier": {
      "type": "string",
      "example": "dpd_de"
    },
    "parameters": {
      "type": "object"
    }
  }
}

object CarrierAccountFedExCreateRequest

{
  "type": "object",
  "title": "Shippo FedEx account",
  "required": [
    "carrier",
    "parameters"
  ],
  "properties": {
    "carrier": {
      "type": "string",
      "example": "fedex"
    },
    "parameters": {
      "type": "object"
    }
  }
}

object CarrierAccountHermesUKCreateRequest

{
  "type": "object",
  "title": "Shippo Evri UK account",
  "required": [
    "carrier",
    "parameters"
  ],
  "properties": {
    "carrier": {
      "type": "string",
      "example": "hermes_uk"
    },
    "parameters": {
      "type": "object"
    }
  }
}

object CarrierAccountMondialRelayCreateRequest

{
  "type": "object",
  "title": "Shippo Mondial Relay account",
  "required": [
    "carrier",
    "parameters"
  ],
  "properties": {
    "carrier": {
      "type": "string",
      "example": "mondialrelay"
    },
    "parameters": {
      "type": "object"
    }
  }
}

object CarrierAccountPaginatedList

{
  "allOf": [
    {
      "$ref": "#/components/schemas/PaginatedList"
    },
    {
      "properties": {
        "results": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/CarrierAccountWithExtraInfo"
          }
        }
      }
    }
  ]
}

object CarrierAccountPosteItalianeCreateRequest

{
  "type": "object",
  "title": "Shippo Poste Italiane account",
  "required": [
    "carrier",
    "parameters"
  ],
  "properties": {
    "carrier": {
      "type": "string",
      "example": "poste_italiane"
    },
    "parameters": {
      "type": "object"
    }
  }
}

object CarrierAccountRegistrationStatus

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "example": "PENDING_TERMS"
    },
    "object_owner": {
      "type": "string",
      "example": "tom@gmail.com"
    },
    "object_created": {
      "type": "string",
      "format": "date-time"
    },
    "object_updated": {
      "type": "string",
      "format": "date-time"
    },
    "carrier_account": {
      "type": "string",
      "example": "99dc410d295b4a168993cc38809cb123"
    }
  }
}

object CarrierAccountServiceLevel

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "example": "Priority Mail Express",
      "description": "Service level name, e.g. `Priority Mail` or `FedEx Ground®`. \nA service level commonly defines the transit time of a Shipment (e.g., Express vs. Standard), along with other properties. \nThese names vary depending on the provider.<br>\nSee <a href=\"#tag/Service-Levels\">Service Levels</a>."
    },
    "token": {
      "type": "string",
      "example": "usps_priority_express",
      "description": "Service level token, e.g. `usps_priority` or `fedex_ground`.<br>\nSee <a href=\"#tag/Service-Levels\">Service Levels</a>."
    },
    "supports_return_labels": {
      "type": "boolean",
      "example": true,
      "description": "Whether or not the service level supports return labels."
    }
  },
  "description": "Contains details regarding the service level for the carrier account."
}

object CarrierAccountUPSCreateRequest

{
  "type": "object",
  "title": "Shippo UPS account",
  "required": [
    "carrier"
  ],
  "properties": {
    "carrier": {
      "type": "string",
      "example": "ups"
    },
    "parameters": {
      "$ref": "#/components/schemas/CarrierAccountUPSCreateRequestParameters"
    }
  }
}

object CarrierAccountUPSCreateRequestParameters

{
  "type": "object",
  "required": [
    "ups_agreements",
    "billing_address_street1",
    "billing_address_city",
    "billing_address_zip",
    "billing_address_state",
    "billing_address_country_iso2",
    "pickup_address_street1",
    "pickup_address_city",
    "pickup_address_zip",
    "pickup_address_state",
    "pickup_address_country_iso2"
  ],
  "properties": {
    "email": {
      "type": "string",
      "example": "hippo@shippo.com"
    },
    "phone": {
      "type": "string",
      "example": "1112223333",
      "description": "Needs to be a valid phone number and cannot be null"
    },
    "company": {
      "type": "string",
      "example": "Shippo",
      "description": "Company name. Full name is acceptable in this field if the user has no company name"
    },
    "full_name": {
      "type": "string",
      "example": "Shippo Meister"
    },
    "ups_agreements": {
      "type": "boolean",
      "description": "Whether the user agrees to the UPS terms and conditions or not. Error 400 will be returned if passed in as false"
    },
    "pickup_address_zip": {
      "type": "string",
      "example": "94103",
      "maxLength": 5,
      "minLength": 5,
      "description": "User's pickup address zip code."
    },
    "billing_address_zip": {
      "type": "string",
      "example": "94103",
      "maxLength": 5,
      "minLength": 5
    },
    "pickup_address_city": {
      "type": "string",
      "example": "San Francisco",
      "description": "User's pickup address city."
    },
    "billing_address_city": {
      "type": "string",
      "example": "San Francisco"
    },
    "pickup_address_state": {
      "type": "string",
      "example": "CA",
      "maxLength": 2,
      "minLength": 2,
      "description": "User's pickup address state."
    },
    "billing_address_state": {
      "type": "string",
      "example": "CA",
      "maxLength": 2,
      "minLength": 2
    },
    "pickup_address_street1": {
      "type": "string",
      "example": "731 Market St",
      "description": "User's pickup address street 1."
    },
    "pickup_address_street2": {
      "type": "string",
      "example": "STE 200",
      "description": "User's pickup street 2."
    },
    "billing_address_street1": {
      "type": "string",
      "example": "731 Market St"
    },
    "billing_address_street2": {
      "type": "string",
      "example": "STE 200",
      "description": "Empty string acceptable for billing_address_street2"
    },
    "pickup_address_country_iso2": {
      "type": "string",
      "example": "US",
      "maxLength": 2,
      "minLength": 2,
      "description": "User's pickup street 1."
    },
    "billing_address_country_iso2": {
      "type": "string",
      "example": "US",
      "maxLength": 2,
      "minLength": 2
    },
    "pickup_address_same_as_billing_address": {
      "type": "boolean",
      "example": false
    }
  }
}

object CarrierAccountUSPSCreateRequest

{
  "type": "object",
  "title": "Shippo USPS account",
  "required": [
    "carrier",
    "parameters"
  ],
  "properties": {
    "carrier": {
      "type": "string",
      "example": "usps"
    },
    "parameters": {
      "type": "object"
    }
  }
}

object CarrierAccountWithExtraInfo

{
  "allOf": [
    {
      "$ref": "#/components/schemas/CarrierAccount"
    },
    {
      "properties": {
        "object_info": {
          "type": "object",
          "properties": {
            "authentication": {
              "type": "object",
              "properties": {
                "type": {
                  "enum": [
                    "default",
                    "oauth"
                  ],
                  "type": "string",
                  "description": "Authentication method used by this account."
                },
                "status": {
                  "enum": [
                    "disconnected",
                    "connected",
                    "authorization_pending"
                  ],
                  "type": "string",
                  "description": "Current authentication status. Possible values: 'disconnected' (authorization lost, reconnect needed), 'connected' (authorized and active), 'authorization_pending' (awaiting initial authorization flow)."
                }
              }
            }
          },
          "description": "Holds internal state relevant to users."
        }
      }
    }
  ]
}

object CarrierAccountsAddShippoAccountRequest

{
  "oneOf": [
    {
      "$ref": "#/components/schemas/CarrierAccountCanadaPostCreateRequest"
    },
    {
      "$ref": "#/components/schemas/CarrierAccountChronopostCreateRequest"
    },
    {
      "$ref": "#/components/schemas/CarrierAccountColissimoCreateRequest"
    },
    {
      "$ref": "#/components/schemas/CarrierAccountCorreosCreateRequest"
    },
    {
      "$ref": "#/components/schemas/CarrierAccountDeutschePostCreateRequest"
    },
    {
      "$ref": "#/components/schemas/CarrierAccountDHLExpressCreateRequest"
    },
    {
      "$ref": "#/components/schemas/CarrierAccountDpdDeCreateRequest"
    },
    {
      "$ref": "#/components/schemas/CarrierAccountDPDUKCreateRequest"
    },
    {
      "$ref": "#/components/schemas/CarrierAccountFedExCreateRequest"
    },
    {
      "$ref": "#/components/schemas/CarrierAccountHermesUKCreateRequest"
    },
    {
      "$ref": "#/components/schemas/CarrierAccountMondialRelayCreateRequest"
    },
    {
      "$ref": "#/components/schemas/CarrierAccountPosteItalianeCreateRequest"
    },
    {
      "$ref": "#/components/schemas/CarrierAccountUPSCreateRequest"
    },
    {
      "$ref": "#/components/schemas/CarrierAccountUSPSCreateRequest"
    }
  ]
}

object CarrierAccountsInitiateSignIn401Response

{
  "type": "object",
  "example": {},
  "properties": {}
}

object CarrierAccountsInitiateSignIn422Response

{
  "type": "object",
  "example": {},
  "properties": {}
}

Load more schemas

Versions

Version	Endpoints	Schemas	Ingested	Status
2018-02-08	64	213	2026-05-11	current
2018-02-08	64	213	2026-04-16