# Shippo external API. Use this API to integrate with the Shippo service Version: 2018-02-08 ## Servers ``` https://api.goshippo.com ``` ## Security ### APIKeyHeader Type: apiKey In: header Name: Authorization ## Download OpenAPI description [Shippo external API.](https://docs.goshippo.com/_bundle/shippoapi/public-api.yaml) ## Addresses Addresses are the locations a parcel is being shipped **from** and **to**. They represent company and residential places. Among other things, you can use address objects to create shipments, calculate shipping rates, and purchase shipping labels. ### List all addresses - [GET /addresses](https://docs.goshippo.com/shippoapi/public-api/addresses/listaddresses.md): Returns a list of all address objects that have been created in this account. ### Create a new address - [POST /addresses](https://docs.goshippo.com/shippoapi/public-api/addresses/createaddress.md): Creates a new address object. You can use address objects to create new shipments, calculate rates, and to create orders. ### Retrieve an address - [GET /addresses/{AddressId}](https://docs.goshippo.com/shippoapi/public-api/addresses/getaddress.md): Returns an existing address using an object ID. ### Validate an address - [GET /addresses/{AddressId}/validate](https://docs.goshippo.com/shippoapi/public-api/addresses/validateaddress.md): Validates an existing address using an object ID ## Parcels A parcel is an item you are shipping. The parcel object includes details about its physical make-up of the parcel. It includes dimensions and weight that Shippo uses to calculate rates. ### List all parcels - [GET /parcels](https://docs.goshippo.com/shippoapi/public-api/parcels/listparcels.md): Returns a list of all parcel objects. ### Create a new parcel - [POST /parcels](https://docs.goshippo.com/shippoapi/public-api/parcels/createparcel.md): Creates a new parcel object. ### Retrieve an existing parcel - [GET /parcels/{ParcelId}](https://docs.goshippo.com/shippoapi/public-api/parcels/getparcel.md): Returns parcel details using an existing parcel object ID (this will not return parcel details associated with un-purchased shipment/rate parcel object IDs). ## Carrier Parcel Templates A carrier parcel template represents a package used for shipping that has preset dimensions defined by a carrier. Some examples of a carrier parcel template include USPS Flat Rate Box and Fedex Small Pak. When using a carrier parcel template, the rates returned may be limited to the carrier that provides the box. You can create user parcel templates using a carrier parcel template. Shippo takes the dimensions of the carrier parcel template but you must configure the weight. ### List all carrier parcel templates - [GET /parcel-templates](https://docs.goshippo.com/shippoapi/public-api/carrier-parcel-templates/listcarrierparceltemplates.md): List all carrier parcel template objects. Use the following query string params to filter the results as needed. include=all (the default). Includes templates from all carriers include=user. Includes templates only from carriers which the user has added (whether or not they're currently enabled) include=enabled. includes templates only for carriers which the user has added and enabled carrier=token. filter by specific carrier, e.g. fedex, usps ### Retrieve a carrier parcel templates - [GET /parcel-templates/{CarrierParcelTemplateToken}](https://docs.goshippo.com/shippoapi/public-api/carrier-parcel-templates/getcarrierparceltemplate.md): Fetches the parcel template information for a specific carrier parcel template, identified by the token. ## User Parcel Templates A user parcel template represents a package used for shipping that has preset dimensions and attributes defined by you. They are useful for capturing attributes of parcel-types you frequently use for shipping, allowing them to be defined once and then used for many shipments. These parcel templates can also be used for live rates. User parcel templates can also be created using a carrier parcel template, where the dimensions will be copied from the carrier presets, but the weight can be configured by you. ### List all user parcel templates - [GET /user-parcel-templates](https://docs.goshippo.com/shippoapi/public-api/user-parcel-templates/listuserparceltemplates.md): Returns a list all of all user parcel template objects. ### Create a new user parcel template - [POST /user-parcel-templates](https://docs.goshippo.com/shippoapi/public-api/user-parcel-templates/createuserparceltemplate.md): Creates a new user parcel template. You can choose to create a parcel template using a preset carrier template as a starting point, or you can create an entirely custom one. To use a preset carrier template, pass in a unique template token from this list plus the weight fields (weight and weight_unit). Otherwise, omit the template field and pass the other fields, for the weight, length, height, and depth, as well as their units." ### Delete a user parcel template - [DELETE /user-parcel-templates/{UserParcelTemplateObjectId}](https://docs.goshippo.com/shippoapi/public-api/user-parcel-templates/deleteuserparceltemplate.md): Deletes a user parcel template using an object ID. ### Retrieves a user parcel template - [GET /user-parcel-templates/{UserParcelTemplateObjectId}](https://docs.goshippo.com/shippoapi/public-api/user-parcel-templates/getuserparceltemplate.md): Returns the parcel template information for a specific user parcel template, identified by the object ID. ### Update an existing user parcel template - [PUT /user-parcel-templates/{UserParcelTemplateObjectId}](https://docs.goshippo.com/shippoapi/public-api/user-parcel-templates/updateuserparceltemplate.md): Updates an existing user parcel template. ## Shipments A shipment is the act of transporting goods. A shipment object contains **to** and **from** addresses, and the parcel details that you are shipping. You can use the shipment object to retrieve shipping rates and purchase a shipping label. ### List all shipments - [GET /shipments](https://docs.goshippo.com/shippoapi/public-api/shipments/listshipments.md): 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 ### Create a new shipment - [POST /shipments](https://docs.goshippo.com/shippoapi/public-api/shipments/createshipment.md): Creates a new shipment object. ### Retrieve a shipment - [GET /shipments/{ShipmentId}](https://docs.goshippo.com/shippoapi/public-api/shipments/getshipment.md): Returns an existing shipment using an object ID ## Rates A rate is the cost to ship a parcel from a carrier. The rate object details the service level including the cost and transit time. ### Retrieve a rate - [GET /rates/{RateId}](https://docs.goshippo.com/shippoapi/public-api/rates/getrate.md): Returns an existing rate using a rate object ID. ### Retrieve shipment rates - [GET /shipments/{ShipmentId}/rates](https://docs.goshippo.com/shippoapi/public-api/rates/listshipmentrates.md): Returns a paginated list of rates associated with a shipment ### Retrieve shipment rates in currency - [GET /shipments/{ShipmentId}/rates/{CurrencyCode}](https://docs.goshippo.com/shippoapi/public-api/rates/listshipmentratesbycurrencycode.md): 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. ## Transactions (shipping labels) A transaction is the purchase of a shipping label from a shipping provider for a specific service. You can print purchased labels and used them to ship a parcel with a carrier, such as USPS or FedEx. ### List all shipping labels - [GET /transactions](https://docs.goshippo.com/shippoapi/public-api/transactions/listtransactions.md): Returns a list of all transaction objects. ### Create a shipping label - [POST /transactions](https://docs.goshippo.com/shippoapi/public-api/transactions/createtransaction.md): Creates a new transaction object and purchases the shipping label using a rate object that has previously been created. OR Creates a new transaction object and purchases the shipping label instantly using shipment details, an existing carrier account, and an existing service level token. ### Retrieve a shipping label - [GET /transactions/{TransactionId}](https://docs.goshippo.com/shippoapi/public-api/transactions/gettransaction.md): Returns an existing transaction using an object ID. ## Batches A batch is a technique for creating multiple labels at once. Use the batch object to create and purchase many shipments in two API calls. After creating the batch, retrieve the batch to verify that all shipments are valid. You can add and remove shipments after you have created the batch. When all shipments are valid you can purchase the batch and retrieve all the shipping labels. ### Create a batch - [POST /batches](https://docs.goshippo.com/shippoapi/public-api/batches/createbatch.md): 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. ### Retrieve a batch - [GET /batches/{BatchId}](https://docs.goshippo.com/shippoapi/public-api/batches/getbatch.md): 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. ### Add shipments to a batch - [POST /batches/{BatchId}/add_shipments](https://docs.goshippo.com/shippoapi/public-api/batches/addshipmentstobatch.md): Adds batch shipments to an existing batch. ### Purchase a batch - [POST /batches/{BatchId}/purchase](https://docs.goshippo.com/shippoapi/public-api/batches/purchasebatch.md): 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 ### Remove shipments from a batch - [POST /batches/{BatchId}/remove_shipments](https://docs.goshippo.com/shippoapi/public-api/batches/removeshipmentsfrombatch.md): Removes shipments from an existing batch shipment. ## Tracking Status


If you purchased your shipping label through Shippo, you can also get all the tracking details of your Shipment from the Transaction object.

A tracking status of a package is an indication of current location of a package in the supply chain. For example, sorting, warehousing, or out for delivery. Use the tracking status object to track the location of your shipments. When using your Test token for tracking, you need to use Shippo's predefined tokens for testing different tracking statuses. You can find more information in our Tracking tutorial on how to do this, and what the payloads look like. ### Register a tracking webhook - [POST /tracks](https://docs.goshippo.com/shippoapi/public-api/tracking-status/createtrack.md): Registers a webhook that will send HTTP notifications to you when the status of your tracked package changes. For more details on creating a webhook, see our guides on Webhooks and Tracking. ### Get a tracking status - [GET /tracks/{Carrier}/{TrackingNumber}](https://docs.goshippo.com/shippoapi/public-api/tracking-status/gettrack.md): Returns the tracking status of a shipment using a carrier name and a tracking number. ## Webhooks Webhooks are a way for Shippo to notify your application when a specific event occurs. For example, when a label is purchased or when a shipment tracking status has changed. You can use webhooks to trigger actions in your application, such as sending an email or updating a database. ### Create a new webhook - [POST /webhooks](https://docs.goshippo.com/shippoapi/public-api/webhooks/createwebhook.md): Creates a new webhook to send notifications to a URL when a specific event occurs. ### List all webhooks - [GET /webhooks](https://docs.goshippo.com/shippoapi/public-api/webhooks/listwebhooks.md): Returns a list of all webhooks you have created. ### Retrieve a specific webhook - [GET /webhooks/{webhookId}](https://docs.goshippo.com/shippoapi/public-api/webhooks/getwebhook.md): Returns the details of a specific webhook using the webhook object ID. ### Update an existing webhook - [PUT /webhooks/{webhookId}](https://docs.goshippo.com/shippoapi/public-api/webhooks/updatewebhook.md): Updates an existing webhook using the webhook object ID. ### Delete a specific webhook - [DELETE /webhooks/{webhookId}](https://docs.goshippo.com/shippoapi/public-api/webhooks/deletewebhook.md): Deletes a specific webhook using the webhook object ID. ## Customs Items Customs declarations are relevant information, including one or multiple customs items, you need to provide for customs clearance for your international shipments. ### List all customs items - [GET /customs/items](https://docs.goshippo.com/shippoapi/public-api/customs-items/listcustomsitems.md): Returns a list all customs items objects. ### Create a new customs item - [POST /customs/items](https://docs.goshippo.com/shippoapi/public-api/customs-items/createcustomsitem.md): Creates a new customs item object. ### Retrieve a customs item - [GET /customs/items/{CustomsItemId}](https://docs.goshippo.com/shippoapi/public-api/customs-items/getcustomsitem.md): Returns an existing customs item using an object ID ## Customs Declarations Customs declarations are relevant information, including one or multiple customs items, you need to provide for customs clearance for your international shipments. ### List all customs declarations - [GET /customs/declarations](https://docs.goshippo.com/shippoapi/public-api/customs-declarations/listcustomsdeclarations.md): Returns a list of all customs declaration objects ### Create a new customs declaration - [POST /customs/declarations](https://docs.goshippo.com/shippoapi/public-api/customs-declarations/createcustomsdeclaration.md): Creates a new customs declaration object ### Retrieve a customs declaration - [GET /customs/declarations/{CustomsDeclarationId}](https://docs.goshippo.com/shippoapi/public-api/customs-declarations/getcustomsdeclaration.md): Returns an existing customs declaration using an object ID ## Carrier Accounts Carriers are the companies who deliver your package. Shippo uses Carrier account objects as credentials to retrieve shipping rates and purchase labels from shipping Carriers. ### List all carrier accounts - [GET /carrier_accounts](https://docs.goshippo.com/shippoapi/public-api/carrier-accounts/listcarrieraccounts.md): 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. ### Create a new carrier account - [POST /carrier_accounts](https://docs.goshippo.com/shippoapi/public-api/carrier-accounts/createcarrieraccount.md): Creates a new carrier account or connects an existing carrier account to the Shippo account. ### Retrieve a carrier account - [GET /carrier_accounts/{CarrierAccountId}](https://docs.goshippo.com/shippoapi/public-api/carrier-accounts/getcarrieraccount.md): Returns an existing carrier account using an object ID. ### Update a carrier account - [PUT /carrier_accounts/{CarrierAccountId}](https://docs.goshippo.com/shippoapi/public-api/carrier-accounts/updatecarrieraccount.md): Updates an existing carrier account object. The account_id and carrier can't be updated. This is because they form the unique identifier together. ### Connect an existing carrier account using OAuth 2.0 - [GET /carrier_accounts/{CarrierAccountObjectId}/signin/initiate](https://docs.goshippo.com/shippoapi/public-api/carrier-accounts/initiateoauth2signin.md): Used by client applications to setup or reconnect an existing carrier account with carriers that support OAuth 2.0 ### Add a Shippo carrier account - [POST /carrier_accounts/register/new](https://docs.goshippo.com/shippoapi/public-api/carrier-accounts/registercarrieraccount.md): Adds a Shippo carrier account ### Get Carrier Registration status - [GET /carrier_accounts/reg-status](https://docs.goshippo.com/shippoapi/public-api/carrier-accounts/getcarrierregistrationstatus.md): Returns the registration status for the given account for the given carrier ## Manifests A manifest is a single-page document with a barcode that carriers can scan to accept all packages into transit without the need to scan each item individually. They are close-outs of shipping labels of a certain day. Some carriers require manifests to process the shipments. ### List all manifests - [GET /manifests](https://docs.goshippo.com/shippoapi/public-api/manifests/listmanifests.md): Returns a list of all manifest objects. ### Create a new manifest - [POST /manifests](https://docs.goshippo.com/shippoapi/public-api/manifests/createmanifest.md): Creates a new manifest object. ### Retrieve a manifest - [GET /manifests/{ManifestId}](https://docs.goshippo.com/shippoapi/public-api/manifests/getmanifest.md): Returns an existing manifest using an object ID. ## Pickups A pickup is when you schedule a carrier to collect a package for delivery. Use Shippo’s pickups endpoint to schedule pickups with USPS and DHL Express for eligible shipments that you have already created. ### Create a pickup - [POST /pickups](https://docs.goshippo.com/shippoapi/public-api/pickups/createpickup.md): Creates a pickup object. This request is for a carrier to come to a specified location to take a package for shipping. ## Orders (beta) An order is a request from a customer to purchase goods from a merchant. Use the orders object to load orders from your system to the Shippo dashboard. You can use the orders object to create, retrieve, list, and manage orders programmatically. You can also retrieve shipping rates, purchase labels, and track shipments for each order. ### List all orders - [GET /orders](https://docs.goshippo.com/shippoapi/public-api/orders/listorders.md): Returns a list of all order objects. ### Create a new order - [POST /orders](https://docs.goshippo.com/shippoapi/public-api/orders/createorder.md): Creates a new order object. ### Retrieve an order - [GET /orders/{OrderId}](https://docs.goshippo.com/shippoapi/public-api/orders/getorder.md): Retrieves an existing order using an object ID. ## Refunds Refunds are reimbursements for successfully created but unused shipping labels or other charges. ### Create a refund - [POST /refunds](https://docs.goshippo.com/shippoapi/public-api/refunds/createrefund.md): Creates a new refund object. ### List all refunds - [GET /refunds/](https://docs.goshippo.com/shippoapi/public-api/refunds/listrefunds.md): Returns a list all refund objects. ### Retrieve a refund - [GET /refunds/{RefundId}](https://docs.goshippo.com/shippoapi/public-api/refunds/getrefund.md): Returns an existing rate using a rate object ID. ## Service Groups A service group is a set of service levels grouped together. Rates at checkout uses services groups to present available shipping options to customers in their shopping basket. ### List all service groups - [GET /service-groups](https://docs.goshippo.com/shippoapi/public-api/service-groups/listservicegroups.md): Returns a list of service group objects. ### Create a new service group - [POST /service-groups](https://docs.goshippo.com/shippoapi/public-api/service-groups/createservicegroup.md): Creates a new service group. ### Update an existing service group - [PUT /service-groups](https://docs.goshippo.com/shippoapi/public-api/service-groups/updateservicegroup.md): Updates an existing service group object. The object_id cannot be updated as it is the unique identifier for the object. ### Delete a service group - [DELETE /service-groups/{ServiceGroupId}](https://docs.goshippo.com/shippoapi/public-api/service-groups/deleteservicegroup.md): Deletes an existing service group using an object ID. ## Rates at Checkout Rates at checkout is a tool for merchants to display up-to-date shipping estimates based on what's in their customers cart and where they’re shipping to. Merchants set up curated shipping options for customers in the checkout flow based on data in the shopping cart. The request must include the **to** address and item information. Optional fields are the **from** address and package information. If the optional fields are not included, the service will use the default address and/or package configured for rates at checkout. The response is a list of shipping options based on the Service Group configuration. (see Service Group configuration for details). # Default Parcel Template Assign one of your user parcel templates to be the default used when generating Live Rates. This template will be used by default when generating Live Rates, unless you explicitly provide a parcel in the Live Rates request. ### Generate a live rates request - [POST /live-rates](https://docs.goshippo.com/shippoapi/public-api/rates-at-checkout/createliverate.md): 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. ### Show current default parcel template - [GET /live-rates/settings/parcel-template](https://docs.goshippo.com/shippoapi/public-api/rates-at-checkout/getdefaultparceltemplate.md): Retrieve and display the currently configured default parcel template for live rates. ### Update default parcel template - [PUT /live-rates/settings/parcel-template](https://docs.goshippo.com/shippoapi/public-api/rates-at-checkout/updatedefaultparceltemplate.md): 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. ### Clear current default parcel template - [DELETE /live-rates/settings/parcel-template](https://docs.goshippo.com/shippoapi/public-api/rates-at-checkout/deletedefaultparceltemplate.md): Clears the currently configured default parcel template for live rates. ## Shippo Accounts Shippo Accounts are used by Shippo Platform Accounts to create and manage Managed Shippo Accounts. Managed Shippo Accounts are headless accounts that represent your customers. They are opaque to your end customers, meaning customers do not need to create their own Shippo login or have a billing relationship with Shippo. They can be used by marketplaces, e-commerce platforms, and third-party logistics providers who want to offer, seamless, built-in shipping functionality to their customers. See our guide for more details. ### List all Shippo Accounts - [GET /shippo-accounts](https://docs.goshippo.com/shippoapi/public-api/shippo-accounts/listshippoaccounts.md): Returns a list of Shippo Managed Accounts objects. ### Create a Shippo Account - [POST /shippo-accounts](https://docs.goshippo.com/shippoapi/public-api/shippo-accounts/createshippoaccount.md): Creates a new Shippo Managed Account. ### Retrieve a Shippo Account - [GET /shippo-accounts/{ShippoAccountId}](https://docs.goshippo.com/shippoapi/public-api/shippo-accounts/getshippoaccount.md): Returns a Shippo Managed Account using an object ID. ### Update a Shippo Account - [PUT /shippo-accounts/{ShippoAccountId}](https://docs.goshippo.com/shippoapi/public-api/shippo-accounts/updateshippoaccount.md): Updates a Shippo Managed Account using an object ID.