API Docs

If you're new to EasyPost, our Getting Started guide will help you get up and shipping quickly.

The samples on this page are available for cURL and all of our client libraries.

If you have any questions please email support@easypost.com.

Authentication

Authentication and identification to the EasyPost API is done by providing an API Key on every request as your Basic Auth username (no password is required). EasyPost also requires that all communication with the API is secured using TLS. Requests made over HTTP or without a proper API Key will fail.

EasyPost provides two types of API Key: Test and Production. You can test all EasyPost functionality using your Test key, for free, immediately after signing up.

You can manage your API Keys from your account.

Remember to treat your API Keys as passwords and keep them secret - they should not be included in public repositories, client side code, etc.

EasyPost Objects

The EasyPost API consists of many object types. There are several attributes that are consistent across all objects:

  • id: Every EasyPost Object that can be created through the API has an id field that is used to refer to the object in other API calls. An id consists of a prefix based on the object type (e.g. Shipments have the prefix "shp_") followed by 32 hex characters. These id values may be used in many API endpoints to refer to an existing object rather than specifying the full object definition; for instance in Shipment creation, you may specify the to_address either with all fields (street1, city, zip, etc.) filled, or you may reuse an existing Address by specifying only the id field value as the matching Address's id, omitting all other fields.
  • object: Every first-class EasyPost object includes an object value. This can be useful for identifying the types of nested objects, or for cases like webhook Events which can contain many different types of result. For objects where there are many variant types, such as Fees, the object value represents the supertype, and the type represents the subtype for that object.
  • reference: Many API objects also have an optional reference field that may be assigned during creation. The reference values you assign may be used in place of id values in many API endpoints, but we recommend using the EasyPost-assigned id instead because ids are guaranteed to be unique within the system, while reference uniqueness is not enforced. If your system does not enforce uniqueness on the references you submit, this may result in the wrong one of many objects with the same reference being picked in EasyPost's handling of your API request.
  • created_at/updated_at: Most API objects also include values for created_at and updated_at. These two fields respectively specify the time the object in question was created and most recently updated. These datetime fields are formatted according to ISO 8601.

Errors

In the event of a client or server error, the response will contain the standard 4xx or 5xx respectively, accompanied by a well-formed JSON body describing the issue, e.g., a required field was omitted, a purchase failed, etc.

Each client library will encapsulate these errors and raise an exception, in addition to other exceptional cases, such as network failures. It is recommended to handle exceptions gracefully and to report any issues to support@easypost.com.

Error Object

attribute type specification
code string Machine readable description of the problem
message string Human readable description of the problem
errors FieldError array Breakdown of errors for specific fields in the request

FieldError Object

attribute type specification
field string Field of the request that the error describes
message string Human readable description of the problem

Common HTTP Status Codes

code reason-phrase description
200 OK The request was successful
201 Created The request was successful and one or more resources was created
400 Bad Request Request not processed due to client error
401 Unauthorized Authentication is required and has failed
402 Payment Required Lack of billing information or insufficient funds
404 Not Found The requested resource could not be found
422 Unprocessable Entity The request was well-formed but unable to process the contained instructions
Full List of Error Codes

Addresses

Address objects are used to represent people, places, and organizations in a number of contexts. For example, a Shipment requires a to_address and from_address to accurately calculate rates and generate postage.

Additionally, EasyPost offers several verification tools that can be used to detect deliverability issues, correct minor errors in spelling/formatting, and determine if an Address is residential or not (which has a significant effect on Shipment rating for many carriers).

Address Object

attribute type specification
id string Unique identifier, begins with "adr_"
object string "Address"
mode string Set based on which api-key you used, either "test" or "production"
street1 string First line of the address
street2 string Second line of the address
city string City the address is located in
state string State or province the address is located in
zip string ZIP or postal code the address is located in
country string ISO 3166 country code for the country the address is located in
residential boolean Whether or not this address would be considered residential
carrier_facility string The specific designation for the address (only relevant if the address is a carrier facility)
name string Name of the person. Both name and company can be included
company string Name of the organization. Both name and company can be included
phone string Phone number to reach the person or organization
email string Email to reach the person or organization
federal_tax_id string Federal tax identifier of the person or organization
state_tax_id string State tax identifier of the person or organization
verifications Verifications The result of any verifications requested

Verifications Object

attribute type specification
zip4 Verification Only applicable to US addresses - checks and sets the ZIP+4.
delivery Verification Checks that the address is deliverable and makes minor corrections to spelling/format. US addresses will also have their "residential" status checked and set.

Verification Object

attribute type specification
success boolean The success of the verification
errors FieldError array All errors that caused the verification to fail

Address Verification by Country

Our address verification service supports 240+ countries. See our full listing to see which verification level is available for each country. We are constantly working to expand our coverage of addresses worldwide.

Full List of Countries & Levels

POST /addresses

Create and Verify Addresses

Depending on your use case an Address can be used in many different ways. Certain carriers allow rating between two zip codes, but full addresses are required to purchase postage. It is recommended to provide as much information as possible during creation and to reuse these objects whenever possible.

Address objects can also be created inline while creating another object, for example during Shipment Creation.

Verify an Address

Verifying an Address before you ship is a great way to reduce issues with delivery.

Creating a verified Address is as simple as including an enumerated list of the verifications you'd like EasyPost to perform in the verify or verify_strict url parameters. If any of the verification checks included in the verify_strict list fail an error will be returned from the API. The example below demonstrates the most common verification: "delivery", which checks that the address is deliverable and sets its residential delivery indicator.

The most effective time to perform address verification is when your customer, or the person entering the delivery address, is present. When designing a shopping cart it is recommended to ask the shopper for their address and verify it on the spot. If verification fails, ask them to double check their input; if they confirm that their data is correct, assume they know their address more correctly than the verification process.

Create Address Request Parameters
param example info
street1 417 Montgomery St First line of the address
street2 Floor 5 Second line of the address
city San Francisco Full city name
state CA State or province
zip 94104 ZIP or postal code
country US ISO 3166 country code for the country the address is located in
name Hiro Protagonist Name of attention, if person. Both name and company can be included
company EasyPost Name of attention, if organization. Both name and company can be included
phone 415-123-4567 Phone number to reach the person or organization
email example@example.com Email to reach the person or organization
residential false Residential delivery indicator
carrier_facility ONDC The specific designation for the address (only relevant if the address is a carrier facility)
federal_tax_id 1234567890 Federal tax identifier of the person or organization
state_tax_id 9876543210 State tax identifier of the person or organization
verify [delivery, zip4] The verifications to perform when creating. verify_strict takes precedence
verify_strict [delivery, zip4] The verifications to perform when creating. The failure of any of these verifications causes the whole request to fail

Create Address Example


curl -X POST https://api.easypost.com/v2/addresses \
  -u <YOUR_TEST/PRODUCTION_API_KEY>: \
  -d "address[street1]=417 MONTGOMERY ST" \
  -d "address[street2]=FLOOR 5" \
  -d "address[city]=SAN FRANCISCO" \
  -d "address[state]=CA" \
  -d "address[zip]=94104" \
  -d "address[country]=US" \
  -d "address[company]=EasyPost" \
  -d "address[phone]=415-123-4567"

{
  "id": "adr_a6fd5dd822c94bdfa1e3f2d28a4dbf9c",
  "object": "Address",
  "mode": "test",
  "created_at": "2015-12-21T21:33:51Z",
  "updated_at": "2015-12-21T21:33:51Z",
  "street1": "417 MONTGOMERY ST",
  "street2": "FLOOR 5",
  "city": "SAN FRANCISCO",
  "state": "CA",
  "zip": "94104",
  "country": "US",
  "residential": null,
  "carrier_facility": null,
  "name": null,
  "company": "EasyPost",
  "phone": "4151234567",
  "email": null,
  "federal_tax_id": null,
  "state_tax_id": null,
  "verifications": {}
}

curl -X POST https://api.easypost.com/v2/addresses \
  -u <YOUR_TEST/PRODUCTION_API_KEY>: \
  -d "verify[]=delivery" \
  -d "address[street1]=417 Montgomery Street" \
  -d "address[street2]=5" \
  -d "address[city]=SF" \
  -d "address[state]=CA" \
  -d "address[zip]=94104" \
  -d "address[country]=US" \
  -d "address[company]=EasyPost" \
  -d "address[phone]=415-123-4567"

{
  "id": "adr_3dc0df9695654f1f8a788e1c872a0769",
  "object": "Address",
  "created_at": "2015-12-22T19:28:06Z",
  "updated_at": "2015-12-22T19:28:06Z",
  "name": null,
  "company": "EasyPost",
  "street1": "417 MONTGOMERY ST",
  "street2": "FL 5",
  "city": "SAN FRANCISCO",
  "state": "CA",
  "zip": "94104-110",
  "country": "US",
  "phone": "4151234567",
  "email": null,
  "mode": "test",
  "carrier_facility": null,
  "residential": null,
  "federal_tax_id": null,
  "state_tax_id": null,
  "verifications": {
    "delivery": {
      "success": true,
      "errors": []
    }
  }
}

curl -X POST https://api.easypost.com/v2/addresses \
  -u <YOUR_TEST/PRODUCTION_API_KEY>: \
  -d "verify[]=delivery" \
  -d "address[street1]=UNDELIVERABLE ST" \
  -d "address[city]=SAN FRANCISCO" \
  -d "address[state]=CA" \
  -d "address[zip]=94104" \
  -d "address[country]=US" \
  -d "address[company]=EasyPost" \
  -d "address[phone]=415-123-4567"

{
  "id": "adr_3618edae14874ff88d54ddfe94f21a41",
  "object": "Address",
  "created_at": "2015-12-22T19:37:23Z",
  "updated_at": "2015-12-22T19:37:23Z",
  "name": null,
  "company": "EasyPost",
  "street1": "UNDELIVERABLE ST",
  "street2": null,
  "city": "SAN FRANCISCO",
  "state": "CA",
  "zip": "94104",
  "country": "US",
  "phone": "4151234567",
  "email": null,
  "mode": "test",
  "carrier_facility": null,
  "residential": null,
  "federal_tax_id": null,
  "state_tax_id": null,
  "verifications": {
    "delivery": {
      "success": false,
      "errors": [
        {"field": "address", "message": "Address not found"},
        {"field": "address", "message": "Insufficient/incorrect address data"}
      ]
    }
  }
}

curl -X POST https://api.easypost.com/v2/addresses \
  -u <YOUR_TEST/PRODUCTION_API_KEY>: \
  -d "verify_strict[]=delivery" \
  -d "address[street1]=UNDELIVERABLE ST" \
  -d "address[city]=SAN FRANCISCO" \
  -d "address[state]=CA" \
  -d "address[zip]=94104" \
  -d "address[country]=US" \
  -d "address[company]=EasyPost" \
  -d "address[phone]=415-123-4567"

{
  "error": {
    "code": "ADDRESS.VERIFY.FAILURE",
    "message": "Address Not Found.  ",
    "errors": []
  }
}
GET /addresses/:id

Retrieve an Address

An Address can be retrieved by either its id or reference. However it is recommended to use EasyPost's provided identifiers because uniqueness on reference is not enforced.

Retrieve Address Example


curl -X GET https://api.easypost.com/v2/addresses/adr_... \
  -u <YOUR_TEST/PRODUCTION_API_KEY>:

{
  "id": "adr_a6fd5dd822c94bdfa1e3f2d28a4dbf9b",
  "object": "Address",
  "mode": "test",
  "created_at": "2015-12-21T21:33:51Z",
  "updated_at": "2015-12-21T21:33:51Z",
  "street1": "417 MONTGOMERY ST",
  "street2": "FLOOR 5",
  "city": "SAN FRANCISCO",
  "state": "CA",
  "zip": "94104",
  "country": "US",
  "residential": null,
  "carrier_facility": null,
  "name": null,
  "company": "EasyPost",
  "phone": "4151234567",
  "email": null,
  "federal_tax_id": null,
  "state_tax_id": null,
  "verifications": {},
}

Parcels

Parcel objects represent the physical container being shipped. Dimensions can be supplied either as length, width, and height dimensions, or a predefined_package string. If you provide a carrier specific predefined_package the associated Shipment will only fetch rates from that carrier.

Weights are in OUNCES (OZ) and go to one decimal point.

Dimensions are in INCHES (IN) and go to one decimal point.

Parcel Object

attribute type specification
id string Unique, begins with "prcl_"
object string "Parcel"
mode string "test" or "production"
length float (inches) Required if predefined_package is empty
width float (inches) Required if predefined_package is empty
height float (inches) Required if predefined_package is empty
predefined_package string Optional, one of our predefined_packages
weight float (oz) Always required
created_at datetime
updated_at datetime

Predefined Packages

Use Predefined Packages with weight only. Dimensions are already defined so they're unnecessary.

These Predefined Packages will only return rates for their respective carrier.

Aramex

No predefined packages for Aramex.

Asendia

No predefined packages for Asendia.

Australia Post

No predefined packages for Australia Post.

Bluedart

No predefined packages for Bluedart.

Boxberry

No predefined packages for Boxberry.

Cainiao

No predefined packages for Cainiao.

Canada Post

No predefined packages for Canada Post.

Canpar

No predefined packages for Canpar.

China Post

No predefined packages for China Post.

Chronopost

No predefined packages for Chronopost.

Colis Privé

No predefined packages for Colis Privé.

Colissimo

No predefined packages for Colissimo.

Correios

No predefined packages for Correios.

DHL Express
  • JumboDocument
  • JumboParcel
  • Document
  • DHLFlyer
  • Domestic
  • ExpressDocument
  • DHLExpressEnvelope
  • JumboBox
  • JumboJuniorDocument
  • JuniorJumboBox
  • JumboJuniorParcel
  • OtherDHLPackaging
  • Parcel
  • YourPackaging
DHL Freight

No predefined packages for DHL Freight.

DHL Germany

No predefined packages for DHL Germany.

DHL Global Mail
  • Letter
  • Flat
  • BPM
  • Parcel
DPD
  • Parcel
  • Pallet
  • ExpressPak
  • FreightParcel
Delhivery

No predefined packages for Delhivery.

Deliv

No predefined packages for Deliv.

Deutsche Post

No predefined packages for Deutsche Post.

EC Firstclass

No predefined packages for EC Firstclass.

EMS

No predefined packages for EMS.

Ecom Express

No predefined packages for Ecom Express.

Fastway
  • Parcel
  • Satchel
FedEx
  • FedExEnvelope
  • FedExBox
  • FedExPak
  • FedExTube
  • FedEx10kgBox
  • FedEx25kgBox
  • FedExSmallBox
  • FedExMediumBox
  • FedExLargeBox
  • FedExExtraLargeBox
FedEx Mailview

No predefined packages for FedEx Mailview.

FedEx SmartPost

No predefined packages for FedEx SmartPost.

FedEx UK

No predefined packages for FedEx UK.

Flyt Express

No predefined packages for Flyt Express.

GLS

No predefined packages for GLS.

GSO

No predefined packages for GSO.

Hong Kong Post

No predefined packages for Hong Kong Post.

IMEX

No predefined packages for IMEX.

India Post

No predefined packages for India Post.

Interlink Express

No predefined packages for Interlink Express.

JP Post

No predefined packages for JP Post.

LSO

No predefined packages for LSO.

La Poste

No predefined packages for La Poste.

LaserShip
  • Box
  • Tube
  • Pak
  • Envelope
  • Custom
Nanjing Woyuan

No predefined packages for Nanjing Woyuan.

New Zealand Post

No predefined packages for New Zealand Post.

Norco

No predefined packages for Norco.

Nova Poshta

No predefined packages for Nova Poshta.

OnTrac
  • Letter
OnTrac DirectPost

No predefined packages for OnTrac DirectPost.

POS Malaysia

No predefined packages for POS Malaysia.

Parcelforce

No predefined packages for Parcelforce.

PostNL
  • Parcel
  • Letter
PostNord

No predefined packages for PostNord.

Postmates

No predefined packages for Postmates.

Purolator
  • CustomerPackaging
  • ExpressPack
  • ExpressBox
  • ExpressEnvelope
R+L Carriers

No predefined packages for R+L Carriers.

Royal Mail
  • Letter
  • LargeLetter
  • SmallParcel
  • MediumParcel
SMSA Express

No predefined packages for SMSA Express.

Spee-Dee

No predefined packages for Spee-Dee.

TNT Express
  • Letter
  • Parcel
UPS
  • UPSLetter
  • UPSExpressBox
  • UPS25kgBox
  • UPS10kgBox
  • Tube
  • Pak
  • Pallet
  • SmallExpressBox
  • MediumExpressBox
  • LargeExpressBox
UPS Mail Innovations

No predefined packages for UPS Mail Innovations.

  • Card
  • Letter
  • Flat
  • Parcel
  • LargeParcel
  • IrregularParcel
  • FlatRateEnvelope
  • FlatRateLegalEnvelope
  • FlatRatePaddedEnvelope
  • FlatRateGiftCardEnvelope
  • FlatRateWindowEnvelope
  • FlatRateCardboardEnvelope
  • SmallFlatRateEnvelope
  • SmallFlatRateBox
  • MediumFlatRateBox
  • LargeFlatRateBox
  • RegionalRateBoxA
  • RegionalRateBoxB
  • LargeFlatRateBoardGameBox
Uber RUSH

No predefined packages for Uber RUSH.

Yanwen

No predefined packages for Yanwen.

Yodel

No predefined packages for Yodel.

Yun Express

No predefined packages for Yun Express.

POST /parcels

Create a Parcel

Include the weight, and either a predefined_package or length, width and height.

Create Parcel Request Parameters
param example
length20.2
width10.9
height5
weight65.9

Create Parcel Example


curl -X POST https://api.easypost.com/v2/parcels \
  -u <YOUR_TEST/PRODUCTION_API_KEY>: \
  -d 'parcel[length]=20.2' \
  -d 'parcel[width]=10.9' \
  -d 'parcel[height]=5' \
  -d 'parcel[weight]=65.9'

{
  "id": "prcl_WDv2VzHp",
  "object": "Parcel",
  "length": 20.2,
  "width": 10.9,
  "height": 5.0,
  "predefined_package": null,
  "weight": 65.9,
  "created_at": "2013-04-22T05:40:57Z",
  "updated_at": "2013-04-22T05:40:57Z"
}
GET /parcels/:id

Retrieve a Parcel

Get a Parcel by its id. In general you should not need to use this in your automated solution. A Parcel's id can be inlined into the creation call to other objects. This allows you to only create one Parcel for each package you will be using.

Retrieve Parcel Example


curl -X GET https://api.easypost.com/v2/parcels/prcl_... \
  -u <YOUR_TEST/PRODUCTION_API_KEY>:

{
  "id": "prcl_WDv2VzHp",
  "object": "Parcel",
  "length": 20.2,
  "width": 10.9,
  "height": 5.0,
  "predefined_package": null,
  "weight": 65.9,
  "created_at": "2013-04-22T05:40:57Z",
  "updated_at": "2013-04-22T05:40:57Z"
}

Shipments

The workhorse of the EasyPost API, a Shipment is made up of a "to" and "from" Address, the Parcel being shipped, and any customs forms required for international deliveries. Once created a Shipment object is used to retrieve shipping Rates and purchase a label.

A Shipment created with a valid to_address, from_address, and parcel will automatically populate its rates attribute.

Note: USPS Commercial Plus Prices show up in the Production API only, not in Test mode.

Shipment Object

attribute type specification
id string Unique, begins with "shp_"
object string "Shipment"
reference string An optional field that may be used in place of id in other API endpoints
mode string "test" or "production"
to_address Address The destination address
from_address Address The origin address
return_address Address The shipper's address, defaults to from_address
buyer_address Address The buyer's address, defaults to to_address
parcel Parcel The dimensions and weight of the package
customs_info CustomsInfo Information for the processing of customs
scan_form ScanForm Document created to manifest and scan multiple shipments
forms Form array All associated Form objects
insurance Insurance The associated Insurance object
rates Rate array All associated Rate objects
selected_rate Rate The specific rate purchased for the shipment, or null if unpurchased or purchased through another mechanism
postage_label PostageLabel The associated PostageLabel object
messages Message array Any carrier errors encountered during rating, discussed in more depth below
options Options All of the options passed to the shipment, discussed in more depth below
is_return boolean Set true to create as a return, discussed in more depth below
tracking_code string If purchased, the tracking code will appear here as well as within the Tracker object
usps_zone string The USPS zone of the shipment, if purchased with USPS
status string The current tracking status of the shipment
tracker Tracker The associated Tracker object
fees Fee array The associated Fee objects charged to the billing user account
refund_status string The current status of the shipment refund process. Possible values are "submitted", "refunded", "rejected".
batch_id string The ID of the batch that contains this shipment, if any
batch_status string The current state of the associated BatchShipment
batch_message string The current message of the associated BatchShipment
created_at datetime
updated_at datetime
POST /shipments

Create a Shipment

A Shipment is almost exclusively a container for other objects, and thus a Shipment may reuse many of these objects. Additionally, all the objects contained within a Shipment may be created at the same time.

The origin/destination Address and Parcel are required for rating. CustomsInfo is required to rate an international Shipment, this includes when the destination is a US Territory. The associated Tracker, Fees, and Rates are generated by EasyPost and cannot be modified by the user.

You can limit the CarrierAccounts to use for rating by passing the carrier_accounts parameter.

Create Shipment Request Parameters
param example
reference "my-reference"
to_address <Address>
from_address <Address>
parcel <Parcel>
carrier_accounts ["ca_f02596dcabbb46a8ba823280efc277bb", ...]

Create Shipment Example


curl -X POST https://api.easypost.com/v2/shipments \
  -u <YOUR_TEST/PRODUCTION_API_KEY>: \
  -d 'shipment[to_address][id]=adr_...' \
  -d 'shipment[from_address][id]=adr_...' \
  -d 'shipment[parcel][id]=prcl_...' \
  -d 'shipment[customs_info][id]=cstinfo_...'

#OR Create A Shipment With One Call

curl -X POST https://api.easypost.com/v2/shipments \
  -u <YOUR_TEST/PRODUCTION_API_KEY>: \
  -d 'shipment[to_address][name]=Dr. Steve Brule' \
  -d 'shipment[to_address][street1]=179 N Harbor Dr' \
  -d 'shipment[to_address][city]=Redondo Beach' \
  -d 'shipment[to_address][state]=CA' \
  -d 'shipment[to_address][zip]=90277' \
  -d 'shipment[to_address][country]=US' \
  -d 'shipment[to_address][phone]=8573875756' \
  -d 'shipment[to_address][email]=dr_steve_brule@gmail.com' \
  -d 'shipment[from_address][name]=EasyPost' \
  -d 'shipment[from_address][street1]=417 Montgomery Street' \
  -d 'shipment[from_address][street2]=5th Floor' \
  -d 'shipment[from_address][city]=San Francisco' \
  -d 'shipment[from_address][state]=CA' \
  -d 'shipment[from_address][zip]=94104' \
  -d 'shipment[from_address][country]=US' \
  -d 'shipment[from_address][phone]=4153334445' \
  -d 'shipment[from_address][email]=support@easypost.com' \
  -d 'shipment[parcel][length]=20.2' \
  -d 'shipment[parcel][width]=10.9' \
  -d 'shipment[parcel][height]=5' \
  -d 'shipment[parcel][weight]=65.9' \
  -d 'shipment[customs_info][id]=cstinfo_...'

{
  "id": "shp_vN9h7XLn",
  "object": "Shipment",
  "mode": "test",
  "to_address": {
    "id": "adr_zMlCRtmt",
    "object": "Address",
    "name": "Dr. Steve Brule",
    "company": null,
    "street1": "179 N Harbor Dr",
    "street2": null,
    "city": "Redondo Beach",
    "state": "CA",
    "zip": "90277",
    "country": "US",
    "phone": "4153334444",
    "mode": "test",
    "carrier_facility": null,
    "residential": null,
    "email": "dr_steve_brule@gmail.com",
    "created_at": "2013-04-22T05:39:56Z",
    "updated_at": "2013-04-22T05:39:56Z"
  },
  "from_address": {
    "id": "adr_VgoLT6Ex",
    "object": "Address",
    "name": "EasyPost",
    "company": null,
    "street1": "417 Montgomery Street",
    "street2": "5th Floor",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94104",
    "country": "US",
    "phone": "4153334444",
    "email": "support@easypost.com",
    "mode": "test",
    "carrier_facility": null,
    "residential": null,
    "created_at": "2013-04-22T05:39:57Z",
    "updated_at": "2013-04-22T05:39:57Z"
  },
  "parcel": {
    "id": "prcl_SI55pjx8",
    "object": "Parcel",
    "length": 20.2,
    "width": 10.9,
    "height": 5.0,
    "predefined_package": null,
    "weight": 140.8,
    "created_at": "2013-04-22T05:39:57Z",
    "updated_at": "2013-04-22T05:39:57Z"
  },
  "customs_info": {
    "id": "cstinfo_iNAizey5",
    "object": "CustomsInfo",
    "created_at": "2013-04-22T05:39:57Z",
    "updated_at": "2013-04-22T05:39:57Z",
    "contents_explanation": null,
    "contents_type": "merchandise",
    "customs_certify": false,
    "customs_signer": null,
    "eel_pfc": null,
    "non_delivery_option": "return",
    "restriction_comments": null,
    "restriction_type": "none",
    "customs_items": [
      {
        "id": "cstitem_9eDIbaDR",
        "object": "CustomsItem",
        "description": "Many, many EasyPost stickers.",
        "hs_tariff_number": "123456",
        "origin_country": "US",
        "quantity": 1,
        "value": 879,
        "weight": 140,
        "created_at": "2013-04-22T05:39:57Z",
        "updated_at": "2013-04-22T05:39:57Z"
      }
    ]
  },
  "rates": [
    {
      "id": "rate_nyCb6ubX",
      "object": "Rate",
      "carrier_account_id": "ca_12345678",
      "service": "FirstClassPackageInternationalService",
      "rate": "9.50",
      "carrier": "USPS",
      "shipment_id": "shp_vN9h7XLn",
      "delivery_days": 4,
      "delivery_date": "2013-04-26T05:40:57Z",
      "delivery_date_guaranteed": false,
      "created_at": "2013-04-22T05:40:57Z",
      "updated_at": "2013-04-22T05:40:57Z"
    },
    {
      "id": "rate_uJh8iO2n",
      "object": "Rate",
      "carrier_account_id": "ca_12345678",
      "service": "PriorityMailInternational",
      "rate": "27.40",
      "carrier": "USPS",
      "shipment_id": "shp_vN9h7XLn",
      "delivery_days": 2,
      "delivery_date": "2013-04-24T05:40:57Z",
      "delivery_date_guaranteed": false,
      "created_at": "2013-04-22T05:40:57Z",
      "updated_at": "2013-04-22T05:40:57Z"
    },
    {
      "id": "rate_oZqapNpE",
      "object": "Rate",
      "carrier_account_id": "ca_12345678",
      "service": "ExpressMailInternational",
      "rate": "35.48",
      "carrier": "USPS",
      "shipment_id": "shp_vN9h7XLn",
      "delivery_days": 1,
      "delivery_date": "2013-04-23T05:40:57Z",
      "delivery_date_guaranteed": true,
      "created_at": "2013-04-22T05:40:57Z",
      "updated_at": "2013-04-22T05:40:57Z"
    }
  ],
  "scan_form": null,
  "selected_rate": null,
  "postage_label": null,
  "tracking_code": null,
  "refund_status": null,
  "insurance": null,
  "created_at": "2013-04-22T05:40:57Z",
  "updated_at": "2013-04-22T05:40:57Z"
}
GET /shipments/:id

Retrieve a Shipment

A Shipment can be retrieved by either its id or reference. However it is recommended to use EasyPost's provided identifiers because uniqueness on reference is not enforced.

Retrieve Shipment Example


curl -X GET https://api.easypost.com/v2/shipments/shp_... \
  -u <YOUR_TEST/PRODUCTION_API_KEY>:

{
  "id": "shp_vN9h7XLn",
  "object": "Shipment",
  "mode": "test",
  "to_address": {
    "id": "adr_zMlCRtmt",
    "object": "Address",
    "name": "Dr. Steve Brule",
    "company": null,
    "street1": "179 N Harbor Dr",
    "street2": null,
    "city": "Redondo Beach",
    "state": "CA",
    "zip": "90277",
    "country": "US",
    "phone": "4153334444",
    "mode": "test",
    "carrier_facility": null,
    "residential": null,
    "email": "dr_steve_brule@gmail.com",
    "created_at": "2013-04-22T05:39:56Z",
    "updated_at": "2013-04-22T05:39:56Z"
  },
  "from_address": {
    "id": "adr_VgoLT6Ex",
    "object": "Address",
    "name": "EasyPost",
    "company": null,
    "street1": "417 Montgomery Street",
    "street2": "5th Floor",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94104",
    "country": "US",
    "phone": "4153334444",
    "email": "support@easypost.com",
    "mode": "test",
    "carrier_facility": null,
    "residential": null,
    "created_at": "2013-04-22T05:39:57Z",
    "updated_at": "2013-04-22T05:39:57Z"
  },
  "parcel": {
    "id": "prcl_SI55pjx8",
    "object": "Parcel",
    "length": 20.2,
    "width": 10.9,
    "height": 5.0,
    "predefined_package": null,
    "weight": 140.8,
    "created_at": "2013-04-22T05:39:57Z",
    "updated_at": "2013-04-22T05:39:57Z"
  },
  "customs_info": {
    "id": "cstinfo_iNAizey5",
    "object": "CustomsInfo",
    "created_at": "2013-04-22T05:39:57Z",
    "updated_at": "2013-04-22T05:39:57Z",
    "contents_explanation": null,
    "contents_type": "merchandise",
    "customs_certify": false,
    "customs_signer": null,
    "eel_pfc": null,
    "non_delivery_option": "return",
    "restriction_comments": null,
    "restriction_type": "none",
    "customs_items": [
      {
        "id": "cstitem_9eDIbaDR",
        "object": "CustomsItem",
        "description": "Many, many EasyPost stickers.",
        "hs_tariff_number": "123456",
        "origin_country": "US",
        "quantity": 1,
        "value": 879,
        "weight": 140,
        "created_at": "2013-04-22T05:39:57Z",
        "updated_at": "2013-04-22T05:39:57Z"
      }
    ]
  },
  "rates": [
    {
      "id": "rate_nyCb6ubX",
      "object": "Rate",
      "carrier_account_id": "ca_12345678",
      "service": "FirstClassPackageInternationalService",
      "rate": "9.50",
      "carrier": "USPS",
      "shipment_id": "shp_vN9h7XLn",
      "delivery_days": 4,
      "delivery_date": "2013-04-26T05:40:57Z",
      "delivery_date_guaranteed": false,
      "created_at": "2013-04-22T05:40:57Z",
      "updated_at": "2013-04-22T05:40:57Z"
    }, {
      "id": "rate_uJh8iO2n",
      "object": "Rate",
      "carrier_account_id": "ca_12345678",
      "service": "PriorityMailInternational",
      "rate": "27.40",
      "carrier": "USPS",
      "shipment_id": "shp_vN9h7XLn",
      "delivery_days": 2,
      "delivery_date": "2013-04-24T05:40:57Z",
      "delivery_date_guaranteed": false,
      "created_at": "2013-04-22T05:40:57Z",
      "updated_at": "2013-04-22T05:40:57Z"
    }, {
      "id": "rate_oZqapNpE",
      "object": "Rate",
      "carrier_account_id": "ca_12345678",
      "service": "ExpressMailInternational",
      "rate": "35.48",
      "carrier": "USPS",
      "shipment_id": "shp_vN9h7XLn",
      "delivery_days": 1,
      "delivery_date": "2013-04-23T05:40:57Z",
      "delivery_date_guaranteed": true,
      "created_at": "2013-04-22T05:40:57Z",
      "updated_at": "2013-04-22T05:40:57Z"
    }
  ],
  "scan_form": null,
  "selected_rate": null,
  "postage_label": null,
  "tracking_code": null,
  "refund_status": null,
  "insurance": null,
  "created_at": "2013-04-22T05:40:57Z",
  "updated_at": "2013-04-22T05:40:57Z"
}
POST /shipments/:id/buy

Buy a Shipment

To purchase a Shipment you only need to specify the Rate to purchase. This operation populates the tracking_code and postage_label attributes. The default image format of the associated PostageLabel is PNG. To change this default see the label_format option.

Additionally, insurance may be added during the purchase. To specify an amount to insure, pass the insurance attribute as a string. The currency of all insurance is USD.

Note: USPS Commercial Plus Prices show up in the Production API only, not in Test mode.

Buy Shipment Request Parameters
param example
rate <Rate>
insurance "100.00"

Buy Shipment Example


curl -X POST https://api.easypost.com/v2/shipments/shp_.../buy \
  -u <YOUR_TEST/PRODUCTION_API_KEY>: \
  -d 'rate[id]=rate_...' \
  -d 'insurance=249.99'

{
  "batch_message": null,
  "batch_status": null,
  "created_at": "2013-11-08T15:50:00Z",
  "customs_info": null,
  "from_address": {
    "city": "San Francisco",
    "company": null,
    "country": "US",
    "created_at": "2013-11-08T15:49:59Z",
    "email": null,
    "id": "adr_faGeob9S",
    "mode": "test",
    "name": "EasyPost",
    "object": "Address",
    "phone": "415-379-7678",
    "state": "CA",
    "street1": "417 Montgomery Street",
    "street2": "5th Floor",
    "updated_at": "2013-11-08T15:49:59Z",
    "zip": "94104"
  },
  "id": "shp_vN9h7XLn",
  "insurance": null,
  "is_return": false,
  "mode": "test",
  "object": "Shipment",
  "parcel": {
    "created_at": "2013-11-08T15:49:59Z",
    "height": null,
    "id": "prcl_TXCreKJp",
    "length": null,
    "mode": "test",
    "object": "Parcel",
    "predefined_package": "UPSLetter",
    "updated_at": "2013-11-08T15:49:59Z",
    "weight": 3.0,
    "width": null
  },
  "postage_label": {
    "created_at": "2013-11-08T20:57:32Z",
    "id": "pl_2Np7asmw",
    "integrated_form": "none",
    "label_date": "2013-11-08T20:57:32Z",
    "label_epl2_url": null,
    "label_file_type": "image/png",
    "label_pdf_url": "http://assets.geteasypost.com/postage_labels/label_pdfs/Z7t7o2.pdf",
    "label_resolution": 200,
    "label_size": "4x7",
    "label_type": "default",
    "label_url": "http://assets.geteasypost.com/postage_labels/labels/lUoagDx.png",
    "label_zpl_url": null,
    "object": "PostageLabel",
    "updated_at": "2013-11-08T21:11:14Z"
  },
  "rates": [
    {
      "carrier": "UPS",
      "created_at": "2013-11-08T15:50:02Z",
      "currency": "USD",
      "id": "rate_vWwNuK8z",
      "object": "Rate",
      "rate": "30.44",
      "service": "NextDayAir",
      "shipment_id": "shp_w1xi76n4",
      "updated_at": "2013-11-08T15:50:02Z"
    }, {
      "carrier": "UPS",
      "created_at": "2013-11-08T15:50:02Z",
      "currency": "USD",
      "id": "rate_kqsS35Cx",
      "object": "Rate",
      "rate": "60.28",
      "service": "NextDayAirEarlyAM",
      "shipment_id": "shp_w1xi76n4",
      "updated_at": "2013-11-08T15:50:02Z"
    }
  ],
  "reference": null,
  "refund_status": null,
  "scan_form": null,
  "selected_rate": {
    "carrier": "UPS",
    "created_at": "2013-11-08T15:50:02Z",
    "currency": "USD",
    "id": "rate_vWwNuK8z",
    "object": "Rate",
    "rate": "30.44",
    "service": "NextDayAir",
    "shipment_id": "shp_w1xi76n4",
    "updated_at": "2013-11-08T15:50:02Z"
  },
  "status": "unknown",
  "to_address": {
    "city": "Redondo Beach",
    "company": null,
    "country": "US",
    "created_at": "2013-11-08T15:49:58Z",
    "email": "dr_steve_brule@gmail.com",
    "id": "adr_EyDCpoii",
    "mode": "test",
    "name": "Dr. Steve Brule",
    "object": "Address",
    "phone": null,
    "state": "CA",
    "street1": "179 N Harbor Dr",
    "street2": null,
    "updated_at": "2013-11-08T15:49:58Z",
    "zip": "90277"
  },
  "tracker": {
    "created_at": "2013-11-08T20:57:32Z",
    "id": "trk_k7oNSa1Q",
    "mode": "test",
    "object": "Tracker",
    "shipment_id": "shp_w1xi76n4",
    "status": "unknown",
    "tracking_code": "1ZE6A4850190733810",
    "tracking_details": [ ],
    "updated_at": "2013-11-08T20:58:26Z"
  },
  "tracking_code": "1ZE6A4850190733810",
  "updated_at": "2013-11-08T20:58:26Z"
}
GET /shipments/:id/label

Convert the Label format of a Shipment

A Shipment's PostageLabel can be converted from PNG to other formats. If the PostageLabel was originally generated in a format other than PNG it cannot be converted.

Label Shipment Example


curl -X GET https://api.easypost.com/v2/shipments/shp_.../label \
  -u <YOUR_TEST/PRODUCTION_API_KEY>: \
  -d 'file_format=ZPL'

{
  "batch_message": null,
  "batch_status": null,
  "created_at": "2013-11-08T15:50:00Z",
  "customs_info": null,
  "from_address": {
    "city": "San Francisco",
    "company": null,
    "country": "US",
    "created_at": "2013-11-08T15:49:59Z",
    "email": null,
    "id": "adr_faGeob9S",
    "mode": "test",
    "name": "EasyPost",
    "object": "Address",
    "phone": "415-379-7678",
    "state": "CA",
    "street1": "417 Montgomery Street",
    "street2": "5th Floor",
    "updated_at": "2013-11-08T15:49:59Z",
    "zip": "94104"
  },
  "id": "shp_vN9h7XLn",
  "insurance": null,
  "is_return": false,
  "mode": "test",
  "object": "Shipment",
  "parcel": {
    "created_at": "2013-11-08T15:49:59Z",
    "height": null,
    "id": "prcl_TXCreKJp",
    "length": null,
    "mode": "test",
    "object": "Parcel",
    "predefined_package": "UPSLetter",
    "updated_at": "2013-11-08T15:49:59Z",
    "weight": 3.0,
    "width": null
  },
  "postage_label": {
    "created_at": "2013-11-08T20:57:32Z",
    "id": "pl_2Np7asmw",
    "integrated_form": "none",
    "label_date": "2013-11-08T20:57:32Z",
    "label_epl2_url": null,
    "label_file_type": "image/png",
    "label_pdf_url": "http://assets.geteasypost.com/postage_labels/label_pdfs/Z7t7o2.pdf",
    "label_resolution": 200,
    "label_size": "4x7",
    "label_type": "default",
    "label_url": "http://assets.geteasypost.com/postage_labels/labels/lUoagDx.png",
    "label_zpl_url": "http://assets.geteasypost.com/postage_labels/label_zpls/GG0F5F.zpl",
    "object": "PostageLabel",
    "updated_at": "2013-11-08T21:11:14Z"
  },
  "rates": [
    {
      "carrier": "UPS",
      "created_at": "2013-11-08T15:50:02Z",
      "currency": "USD",
      "id": "rate_vWwNuK8z",
      "object": "Rate",
      "rate": "30.44",
      "service": "NextDayAir",
      "shipment_id": "shp_w1xi76n4",
      "updated_at": "2013-11-08T15:50:02Z"
    }, {
      "carrier": "UPS",
      "created_at": "2013-11-08T15:50:02Z",
      "currency": "USD",
      "id": "rate_kqsS35Cx",
      "object": "Rate",
      "rate": "60.28",
      "service": "NextDayAirEarlyAM",
      "shipment_id": "shp_w1xi76n4",
      "updated_at": "2013-11-08T15:50:02Z"
    }
  ],
  "reference": null,
  "refund_status": null,
  "scan_form": null,
  "selected_rate": {
    "carrier": "UPS",
    "created_at": "2013-11-08T15:50:02Z",
    "currency": "USD",
    "id": "rate_vWwNuK8z",
    "object": "Rate",
    "rate": "30.44",
    "service": "NextDayAir",
    "shipment_id": "shp_w1xi76n4",
    "updated_at": "2013-11-08T15:50:02Z"
  },
  "status": "unknown",
  "to_address": {
    "city": "Redondo Beach",
    "company": null,
    "country": "US",
    "created_at": "2013-11-08T15:49:58Z",
    "email": "dr_steve_brule@gmail.com",
    "id": "adr_EyDCpoii",
    "mode": "test",
    "name": "Dr. Steve Brule",
    "object": "Address",
    "phone": null,
    "state": "CA",
    "street1": "179 N Harbor Dr",
    "street2": null,
    "updated_at": "2013-11-08T15:49:58Z",
    "zip": "90277"
  },
  "tracker": {
    "created_at": "2013-11-08T20:57:32Z",
    "id": "trk_k7oNSa1Q",
    "mode": "test",
    "object": "Tracker",
    "shipment_id": "shp_w1xi76n4",
    "status": "unknown",
    "tracking_code": "1ZE6A4850190733810",
    "tracking_details": [ ],
    "updated_at": "2013-11-08T20:58:26Z"
  },
  "tracking_code": "1ZE6A4850190733810",
  "updated_at": "2013-11-08T20:58:26Z"
}

Options

Shipments can have a variety of additional options which you can specify when creating a shipment. The Options object can be populated with the keys below.

Carrier specific support for each option is added as needed. To request support for a specific carrier option please email us at support@easypost.com.

Options Object

attribute type specification
additional_handling boolean Setting this option to true, will add an additional handling charge. An Additional Handling charge may be applied to the following:
  • Any article that is encased in an outside shipping container made of metal or wood.
  • Any item, such as a barrel, drum, pail or tire, that is not fully encased in a corrugated cardboard shipping container.
  • Any package with the longest side exceeding 60 inches or its second longest side exceeding 30 inches.
  • Any package with an actual weight greater than 70 pounds.
address_validation_level string Setting this option to "0", will allow the minimum amount of address information to pass the validation check. Only for USPS postage.
alcohol boolean Set this option to true if your shipment contains alcohol.
  • UPS - only supported for US Domestic shipments
  • FedEx - only supported for US Domestic shipments
  • Canada Post - Requires adult signature 19 years or older. If you want adult signature 18 years or older, instead use delivery_confirmation: ADULT_SIGNATURE
bill_receiver_account string Setting an account number of the receiver who is to receive and buy the postage.
  • UPS - bill_receiver_postal_code is also required
bill_receiver_postal_code string Setting a postal code of the receiver account you want to buy postage.
  • UPS - bill_receiver_account also required
bill_third_party_account string Setting an account number of the third party account you want to buy postage.
  • UPS - bill_third_party_country and bill_third_party_postal_code also required
bill_third_party_country string Setting a country of the third party account you want to buy postage.
  • UPS - bill_third_party_account and bill_third_party_postal_code also required
bill_third_party_postal_code string Setting a postal code of the third party account you want to buy postage.
  • UPS - bill_third_party_country and bill_third_party_account also required
by_drone boolean Setting this option to true will indicate to the carrier to prefer delivery by drone, if the carrier supports drone delivery.
carbon_neutral boolean Setting this to true will add a charge to reduce carbon emissions.
cod_amount string Adding an amount will have the carrier collect the specified amount from the recipient.
cod_method string Method for payment. "CASH", "CHECK", "MONEY_ORDER"
currency string Which currency this shipment will show for rates if carrier allows.
delivered_duty_paid boolean Setting this value to false will pass the cost of duties on to the recipient of the package(s).
delivery_confirmation string If you want to request a signature, you can pass "ADULT_SIGNATURE" or "SIGNATURE". You may also request "NO_SIGNATURE" to leave the package at the door.
  • All - some options may be limited for international shipments
dry_ice boolean Package contents contain dry ice.
  • UPS - Need dry_ice_weight to be set
  • UPS MailInnovations - Need dry_ice_weight to be set
  • FedEx - Need dry_ice_weight to be set
dry_ice_medical string If the dry ice is for medical use, set this option to true.
  • UPS - Need dry_ice_weight to be set
  • UPS MailInnovations - Need dry_ice_weight to be set
dry_ice_weight string Weight of the dry ice in ounces.
  • UPS - Need dry_ice to be set
  • UPS MailInnovations - Need dry_ice to be set
  • FedEx - Need dry_ice to be set
freight_charge double Additional cost to be added to the invoice of this shipment. Only applies to UPS currently.
handling_instructions string This is to designate special instructions for the carrier like "Do not drop!".
hazmat string Dangerous goods indicator. Possible values are "ORMD" and "LIMITED_QUANTITY". Applies to USPS and FedEx.
hold_for_pickup boolean Package will wait at carrier facility for pickup.
invoice_number string This will print an invoice number on the postage label.
label_date string Set the date that will appear on the postage label. Accepts ISO 8601 formatted string including time zone offset.
label_format string Supported label formats include "PNG", "PDF", "ZPL", and "EPL2". "PNG" is the only format that allows for conversion.
machinable boolean Whether or not the parcel can be processed by the carriers equipment.
print_custom_1 string You can optionally print custom messages on labels. The locations of these fields show up on different spots on the carrier's labels.
print_custom_2 string An additional message on the label. Same restrictions as print_custom_1
print_custom_3 string An additional message on the label. Same restrictions as print_custom_1
print_custom_1_barcode boolean Create a barcode for this custom reference if supported by carrier.
print_custom_2_barcode boolean Create a barcode for this custom reference if supported by carrier.
print_custom_3_barcode boolean Create a barcode for this custom reference if supported by carrier.
print_custom_1_code string Specify the type of print_custom_1.
FedEx
  • (null) - If print_custom_1_code is not provided it defaults to Customer Reference
  • PO - Purchase Order Number
  • DP - Department Number
  • RMA - Return Merchandise Authorization
UPS
  • AJ - Accounts Receivable Customer Account
  • AT - Appropriation Number
  • BM - Bill of Lading Number
  • 9V - Collect on Delivery (COD) Number
  • ON - Dealer Order Number
  • DP - Department Number
  • 3Q - Food and Drug Administration (FDA) Product Code
  • IK - Invoice Number
  • MK - Manifest Key Number
  • MJ - Model Number
  • PM - Part Number
  • PC - Production Code
  • PO - Purchase Order Number
  • RQ - Purchase Request Number
  • RZ - Return Authorization Number
  • SA - Salesperson Number
  • SE - Serial Number
  • ST - Store Number
  • TN - Transaction Reference Number
  • EI - Employer’s ID Number
  • TJ - Federal Taxpayer ID No.
  • SY - Social Security Number
print_custom_2_code string See print_custom_1_code.
print_custom_3_code string See print_custom_1_code.
saturday_delivery boolean Set this value to true for delivery on Saturday. Can't be combined with Next Day Air. When setting the saturday_delivery option, you will only get rates for services that are eligible for saturday delivery. If no services are available for saturday delivery, then you will not be returned any rates. You may need to create 2 shipments, one with the saturday_delivery option set on one without to get all your eligible rates.
special_rates_eligibility string This option allows you to request restrictive rates from USPS. Can set to 'USPS.MEDIAMAIL' or 'USPS.LIBRARYMAIL'.
smartpost_hub string You can use this to override the hub ID you have on your account.
smartpost_manifest string The manifest ID is used to group SmartPost packages onto a manifest for each trailer.
POST /shipments

Create a Shipment with Options

Any number of options can be specified during Shipment creation.

Create Shipment Example


curl -X POST https://api.easypost.com/v2/shipments \
  -u <YOUR_TEST/PRODUCTION_API_KEY>: \
  -d 'shipment[to_address][id]=adr_...' \
  -d 'shipment[from_address][id]=adr_...' \
  -d 'shipment[parcel][id]=prcl_...' \
  -d 'shipment[options][address_validation_level]=0'

{
  "id": "shp_vN9h7XLn",
  "object": "Shipment",
  "mode": "test",
  "options": {"address_validation_level": "0"},
  "to_address": {
    "city": "Redondo Beach",
    "company": null,
    "country": "US",
    "created_at": "2013-11-08T15:49:58Z",
    "email": "dr_steve_brule@gmail.com",
    "id": "adr_EyDCpoii",
    "mode": "test",
    "name": "Dr. Steve Brule",
    "object": "Address",
    "phone": null,
    "state": "CA",
    "street1": "179 N Harbor Dr",
    "street2": null,
    "updated_at": "2013-11-08T15:49:58Z",
    "zip": "90277"
  },
  "from_address": {
    "city": "San Francisco",
    "company": null,
    "country": "US",
    "created_at": "2013-11-08T15:49:59Z",
    "email": null,
    "id": "adr_faGeob9S",
    "mode": "test",
    "name": "EasyPost",
    "object": "Address",
    "phone": "415-379-7678",
    "state": "CA",
    "street1": "417 Montgomery Street",
    "street2": "5th Floor",
    "updated_at": "2013-11-08T15:49:59Z",
    "zip": "94104"
  },
  "parcel": {
    "id": "prcl_SI55pjx8",
    "object": "Parcel",
    "length": 20.2,
    "width": 10.9,
    "height": 5.0,
    "predefined_package": null,
    "weight": 140.8,
    "created_at": "2013-04-22T05:39:57Z",
    "updated_at": "2013-04-22T05:39:57Z"
  },
  "customs_info": {
    "id": "cstinfo_iNAizey5",
    "object": "CustomsInfo",
    "created_at": "2013-04-22T05:39:57Z",
    "updated_at": "2013-04-22T05:39:57Z",
    "contents_explanation": null,
    "contents_type": "merchandise",
    "customs_certify": false,
    "customs_signer": null,
    "eel_pfc": null,
    "non_delivery_option": "return",
    "restriction_comments": null,
    "restriction_type": "none",
    "customs_items": [
      {
        "id": "cstitem_9eDIbaDR",
        "object": "CustomsItem",
        "description": "Many, many EasyPost stickers.",
        "hs_tariff_number": "123456",
        "origin_country": "US",
        "quantity": 1,
        "value": 879,
        "weight": 140,
        "created_at": "2013-04-22T05:39:57Z",
        "updated_at": "2013-04-22T05:39:57Z"
      }
    ]
  },
  "rates": [
    {
      "id": "rate_nyCb6ubX",
      "object": "Rate",
      "service": "FirstClassPackageInternationalService",
      "rate": "9.50",
      "carrier": "USPS",
      "shipment_id": "shp_vN9h7XLn",
      "delivery_days": 4,
      "delivery_date": "2013-04-26T05:40:57Z",
      "delivery_date_guaranteed": false,
      "created_at": "2013-04-22T05:40:57Z",
      "updated_at": "2013-04-22T05:40:57Z"
    }, {
      "id": "rate_uJh8iO2n",
      "object": "Rate",
      "service": "PriorityMailInternational",
      "rate": "27.40",
      "carrier": "USPS",
      "shipment_id": "shp_vN9h7XLn",
      "delivery_days": 2,
      "delivery_date": "2013-04-24T05:40:57Z",
      "delivery_date_guaranteed": false,
      "created_at": "2013-04-22T05:40:57Z",
      "updated_at": "2013-04-22T05:40:57Z"
    }, {
      "id": "rate_oZqapNpE",
      "object": "Rate",
      "service": "ExpressMailInternational",
      "rate": "35.48",
      "carrier": "USPS",
      "shipment_id": "shp_vN9h7XLn",
      "delivery_days": 1,
      "delivery_date": "2013-04-23T05:40:57Z",
      "delivery_date_guaranteed": true,
      "created_at": "2013-04-22T05:40:57Z",
      "updated_at": "2013-04-22T05:40:57Z"
    }
  ],
  "scan_form": null,
  "selected_rate": null,
  "postage_label": null,
  "tracking_code": null,
  "refund_status": null,
  "insurance": null,
  "created_at": "2013-04-22T05:40:57Z",
  "updated_at": "2013-04-22T05:40:57Z"
}

Rates

After a Shipment is successfully created, it will automatically fetch Rates. You can limit the CarrierAccounts to use for rating by passing the carrier_accounts parameter upon Shipment creation.

There are three rate types: the actual rate that will be purchased, rate and currency, the published non-discounted rate, list_rate and list_currency, and the rate if purchased from the post office, retail_rate and retail_currency.

Rate Object

attribute type specification
id string unique, begins with 'rate_'
object string "Rate"
mode string "test" or "production"
service string service level/name
carrier string name of carrier
carrier_account_id string ID of the CarrierAccount record used to generate this rate
shipment_id string ID of the Shipment this rate belongs to
rate string the actual rate quote for this service
currency string currency for the rate
retail_rate string the retail rate is the in-store rate given with no account
retail_currency string currency for the retail rate
list_rate string the list rate is the non-negotiated rate given for having an account with the carrier
list_currency string currency for the list rate
delivery_days int delivery days for this service
delivery_date string date for delivery
delivery_date_guaranteed boolean indicates if delivery window is guaranteed (true) or not (false)
est_delivery_days* integer *This field is deprecated and should be ignored.
created_at datetime
updated_at datetime

Service Levels

Aramex

No service levels for Aramex.

Asendia
  • PMI
  • ePacket
  • IPA
  • ISAL
Australia Post
  • ExpressPost
  • ExpressPostSignature
  • ParcelPost
  • ParcelPostSignature
  • ParcelPostExtra
  • ParcelPostWinePlusSignature
Bluedart

No service levels for Bluedart.

Boxberry
  • Boxberry
Cainiao

No service levels for Cainiao.

Canada Post
  • RegularParcel
  • ExpeditedParcel
  • Xpresspost
  • XpresspostCertified
  • Priority
  • LibraryBooks
  • ExpeditedParcelUSA
  • PriorityWorldwideEnvelopeUSA
  • PriorityWorldwidePakUSA
  • PriorityWorldwideParcelUSA
  • SmallPacketUSAAir
  • TrackedPacketUSA
  • TrackedPacketUSALVM
  • XpresspostUSA
  • XpresspostInternational
  • InternationalParcelAir
  • InternationalParcelSurface
  • PriorityWorldwideEnvelopeIntl
  • PriorityWorldwidePakIntl
  • PriorityWorldwideParcelIntl
  • SmallPacketInternationalAir
  • SmallPacketInternationalSurface
  • TrackedPacketInternational
Canpar
  • Ground
  • SelectLetter
  • SelectPak
  • Select
  • OvernightLetter
  • OvernightPak
  • Overnight
  • SelectUSA
  • USAPak
  • USALetter
  • USA
  • International
China Post

No service levels for China Post.

Chronopost

No service levels for Chronopost.

Colis Privé
  • Parcel
Colissimo
  • InterMonBureauDePoste
  • InterMonCommercant
  • InterMonDomicileAvecSignature
  • InterMonDomicileSansSignature
  • MaConsigneCityssimo
  • MonBureauDePoste
  • MonCommercant
  • MonDomicileAvecSignature
  • MonDomicileSansSignature
  • MonDomicileSurRDV
Correios

No service levels for Correios.

DHL Express
  • BreakBulkEconomy
  • BreakBulkExpress
  • DomesticEconomySelect
  • DomesticExpress
  • DomesticExpress1030
  • DomesticExpress1200
  • EconomySelect
  • EconomySelectNonDoc
  • EuroPack
  • EuropackNonDoc
  • Express1030
  • Express1030NonDoc
  • Express1200NonDoc
  • Express1200
  • Express900
  • Express900NonDoc
  • ExpressEasy
  • ExpressEasyNonDoc
  • ExpressEnvelope
  • ExpressWorldwide
  • ExpressWorldwideB2C
  • ExpressWorldwideB2CNonDoc
  • ExpressWorldwideECX
  • ExpressWorldwideNonDoc
  • FreightWorldwide
  • GlobalmailBusiness
  • JetLine
  • JumboBox
  • LogisticsServices
  • SameDay
  • SecureLine
  • SprintLine
DHL Freight

No service levels for DHL Freight.

DHL Germany

No service levels for DHL Germany.

DHL Global Mail
  • BPMExpeditedDomestic
  • BPMGroundDomestic
  • FlatsExpeditedDomestic
  • FlatsGroundDomestic
  • MediaMailGroundDomestic
  • ParcelPlusExpeditedDomestic
  • ParcelPlusGroundDomestic
  • ParcelsExpeditedDomestic
  • ParcelsGroundDomestic
  • MarketingParcelExpeditedDomestic
  • MarketingParcelGroundDomestic
DPD
  • AirExpressInternationalAir
  • AirClassicInternationalAir
  • ParcelSunday
  • FreightParcelSunday
  • PalletSunday
  • PalletDpdClassic
  • ExpresspakDpdClassic
  • ExpresspakSunday
  • ParcelDpdClassic
  • ParcelDpdTwoDay
  • ParcelDpdNextDay
  • ParcelDpd12
  • ParcelDpd10
  • ParcelDpd10
  • ParcelReturnToShop
  • ParcelSaturday
  • ParcelSaturday12
  • ParcelSaturday10
  • ParcelSaturday10
  • ParcelSunday12
  • FreightParcelDpdClassic
  • FreightParcelSunday12
  • ExpresspakDpdNextDay
  • ExpresspakDpd12
  • ExpresspakDpd10
  • ExpresspakDpd10
  • ExpresspakSaturday
  • ExpresspakSaturday12
  • ExpresspakSaturday10
  • ExpresspakSaturday10
  • ExpresspakSunday12
  • PalletSunday12
  • PalletDpdTwoDay
  • PalletDpdNextDay
  • PalletDpd12
  • PalletDpd10
  • PalletSaturday
  • PalletSaturday12
  • PalletSaturday10
  • FreightParcelDpdTwoDay
  • FreightParcelDpdNextDay
  • FreightParcelDpd12
  • FreightParcelDpd10
  • FreightParcelSaturday
  • FreightParcelSaturday12
  • FreightParcelSaturday10
  • ParcelShipToShop
Delhivery

No service levels for Delhivery.

Deliv
  • Scheduled
  • OnDemand
Deutsche Post

No service levels for Deutsche Post.

EC Firstclass

No service levels for EC Firstclass.

EMS

No service levels for EMS.

Ecom Express

No service levels for Ecom Express.

Fastway
  • Parcel
  • Satchel
FedEx
  • FEDEX_GROUND
  • FEDEX_2_DAY
  • FEDEX_2_DAY_AM
  • FEDEX_EXPRESS_SAVER
  • STANDARD_OVERNIGHT
  • FIRST_OVERNIGHT
  • PRIORITY_OVERNIGHT
  • INTERNATIONAL_ECONOMY
  • INTERNATIONAL_FIRST
  • INTERNATIONAL_PRIORITY
  • GROUND_HOME_DELIVERY
  • SMART_POST
FedEx Mailview

No service levels for FedEx Mailview.

FedEx SmartPost
  • SMART_POST
FedEx UK

No service levels for FedEx UK.

Flyt Express

No service levels for Flyt Express.

GLS

No service levels for GLS.

GSO
  • EarlyPriorityOvernight
  • PriorityOvernight
  • CaliforniaParcelService
  • SaturdayDeliveryService
  • EarlySaturdayService
  • Ground
  • Overnight
Hong Kong Post

No service levels for Hong Kong Post.

IMEX

No service levels for IMEX.

India Post

No service levels for India Post.

Interlink Express
  • InterlinkAirClassicInternationalAir
  • InterlinkAirExpressInternationalAir
  • InterlinkExpresspak1By10:30
  • InterlinkExpresspak1By12
  • InterlinkExpresspak1NextDay
  • InterlinkExpresspak1Saturday
  • InterlinkExpresspak1SaturdayBy10:30
  • InterlinkExpresspak1SaturdayBy12
  • InterlinkExpresspak1Sunday
  • InterlinkExpresspak1SundayBy12
  • InterlinkExpresspak5By10
  • InterlinkExpresspak5By10:30
  • InterlinkExpresspak5By12
  • InterlinkExpresspak5NextDay
  • InterlinkExpresspak5Saturday
  • InterlinkExpresspak5SaturdayBy10
  • InterlinkExpresspak5SaturdayBy10:30
  • InterlinkExpresspak5SaturdayBy12
  • InterlinkExpresspak5Sunday
  • InterlinkExpresspak5SundayBy12
  • InterlinkFreightBy10
  • InterlinkFreightBy12
  • InterlinkFreightNextDay
  • InterlinkFreightSaturday
  • InterlinkFreightSaturdayBy10
  • InterlinkFreightSaturdayBy12
  • InterlinkFreightSunday
  • InterlinkFreightSundayBy12
  • InterlinkParcelBy10
  • InterlinkParcelBy10:30
  • InterlinkParcelBy12
  • InterlinkParcelDpdEuropeByRoad
  • InterlinkParcelNextDay
  • InterlinkParcelReturn
  • InterlinkParcelReturnToShop
  • InterlinkParcelSaturday
  • InterlinkParcelSaturdayBy10
  • InterlinkParcelSaturdayBy10:30
  • InterlinkParcelSaturdayBy12
  • InterlinkParcelShipToShop
  • InterlinkParcelSunday
  • InterlinkParcelSundayBy12
  • InterlinkParcelTwoDay
  • InterlinkPickupParcelDpdEuropeByRoad
JP Post

No service levels for JP Post.

LSO
  • GroundEarly
  • GroundBasic
  • PriorityBasic
  • PriorityEarly
  • PrioritySaturday
  • Priority2ndDay
  • SameDay
La Poste

No service levels for La Poste.

LaserShip
  • SameDay
  • NextDay
Nanjing Woyuan

No service levels for Nanjing Woyuan.

New Zealand Post

No service levels for New Zealand Post.

Norco
  • EarlyOvernite
  • MorningOvernite
  • OneOvernite
  • NextDayOvernite
  • SaturdayOvernite
  • 2DayMetro
  • Ground
  • Overnight
Nova Poshta

No service levels for Nova Poshta.

OnTrac
  • Sunrise
  • Gold
  • OnTrac Gold
  • Ground
  • Overnight
OnTrac DirectPost
  • FirstClassMail
  • PriorityMail
  • BoundPrintedMatter
  • MediaMail
  • ParcelSelect
  • ParcelSelectLightweight
POS Malaysia

No service levels for POS Malaysia.

Parcelforce

No service levels for Parcelforce.

PostNL
  • EUPackSpecialCOD
  • EUPackStandard
  • BelgiumStatedAddressOnlyReturnNotHome
  • BelgiumReturnNotHome
  • BelgiumSignatureStatedAddressOnlyReturnNotHome
  • BelgiumSignatureReturnNotHome
  • BelgiumCODReturnNotHome
  • BelgiumExtraCoverStatedAddressOnlyReturnNotHome
  • BelgiumCODExtraCoverReturnNotHome
  • LetterIDAgeCheck
  • LetterAgeCheck
  • LetterIDCheck
  • StandardShipment
  • COD
  • ExtraCover
  • SignatureStatedAddressOnly
  • DeliveryToNeighbourReturnNotHome
  • CODExtraCover
  • CODReturnNotHome
  • ExtraCoverReturnNotHome
  • SignatureStatedAddressOnlyReturnNotHome
  • CODExtraCoverReturnNotHome
  • Signature
  • StatedAddressOnly
  • SignatureReturnNotHome
  • StatedAddressOnlyReturnNotHome
  • ParcelAgeCheck
  • ParcelIDAgeCheck
  • ParcelIDCheck
PostNord

No service levels for PostNord.

Postmates
  • OnDemand
Purolator
  • PurolatorExpress
  • PurolatorExpress1030AM
  • PurolatorExpress9AM
  • PurolatorExpressBox
  • PurolatorExpressBox1030AM
  • PurolatorExpressBox9AM
  • PurolatorExpressBoxEvening
  • PurolatorExpressBoxInternational
  • PurolatorExpressBoxUS
  • PurolatorExpressEnvelope
  • PurolatorExpressEnvelope1030AM
  • PurolatorExpressEnvelope9AM
  • PurolatorExpressEnvelopeEvening
  • PurolatorExpressEnvelopeInternational
  • PurolatorExpressEnvelopeUS
  • PurolatorExpressEvening
  • PurolatorExpressInternational
  • PurolatorExpressInternational1030AM
  • PurolatorExpressInternational1200
  • PurolatorExpressInternational9AM
  • PurolatorExpressInternationalBox1030AM
  • PurolatorExpressInternationalBox1200
  • PurolatorExpressInternationalBox9AM
  • PurolatorExpressInternationalEnvelope1030AM
  • PurolatorExpressInternationalEnvelope1200
  • PurolatorExpressInternationalEnvelope9AM
  • PurolatorExpressInternationalPack1030AM
  • PurolatorExpressInternationalPack1200
  • PurolatorExpressInternationalPack9AM
  • PurolatorExpressPack
  • PurolatorExpressPack1030AM
  • PurolatorExpressPack9AM
  • PurolatorExpressPackEvening
  • PurolatorExpressPackInternational
  • PurolatorExpressPackUS
  • PurolatorExpressUS
  • PurolatorExpressUS1030AM
  • PurolatorExpressUS1200
  • PurolatorExpressUS9AM
  • PurolatorExpressUSBox1030AM
  • PurolatorExpressUSBox1200
  • PurolatorExpressUSBox9AM
  • PurolatorExpressUSEnvelope1030AM
  • PurolatorExpressUSEnvelope1200
  • PurolatorExpressUSEnvelope9AM
  • PurolatorExpressUSPack1030AM
  • PurolatorExpressUSPack1200
  • PurolatorExpressUSPack9AM
  • PurolatorGround
  • PurolatorGround1030AM
  • PurolatorGround9AM
  • PurolatorGroundDistribution
  • PurolatorGroundEvening
  • PurolatorGroundRegional
  • PurolatorGroundUS
R+L Carriers

No service levels for R+L Carriers.

Royal Mail
  • InternationalSigned
  • InternationalStandard
  • InternationalTracked
  • InternationalTrackedAndSigned
  • 1stClass
  • 1stClassSignedFor
  • 2ndClass
  • 2ndClassSignedFor
  • RoyalMail24
  • RoyalMail24SignedFor
  • RoyalMail48
  • RoyalMail48SignedFor
  • SpecialDeliveryGuaranteed1pm
  • SpecialDeliveryGuaranteed9am
  • StandardLetter1stClass
  • StandardLetter1stClassSignedFor
  • StandardLetter2ndClass
  • StandardLetter2ndClassSignedFor
  • Tracked24
  • Tracked24HighVolume
  • Tracked24HighVolumeSignature
  • Tracked24Signature
  • Tracked48
  • Tracked48HighVolume
  • Tracked48HighVolumeSignature
  • Tracked48Signature
SMSA Express

No service levels for SMSA Express.

Spee-Dee
  • SpeeDeeDelivery
TNT Express
  • 0900Express
  • 1000Express
  • 1200Express
  • EconomyExpress
  • GlobalExpress
  • 0900ExpressDocs
  • 1200ExpressDocs
  • GlobalExpressDocs
UPS
  • Ground
  • UPSStandard
  • UPSSaver
  • Express
  • ExpressPlus
  • Expedited
  • NextDayAir
  • NextDayAirSaver
  • NextDayAirEarlyAM
  • 2ndDayAir
  • 2ndDayAirAM
  • 3DaySelect
UPS Mail Innovations
  • First
  • Priority
  • ExpeditedMailInnovations
  • PriorityMailInnovations
  • EconomyMailInnovations
USPS
  • First
  • Priority
  • Express
  • ParcelSelect
  • LibraryMail
  • MediaMail
  • CriticalMail
  • FirstClassMailInternational
  • FirstClassPackageInternationalService
  • PriorityMailInternational
  • ExpressMailInternational
Uber RUSH
  • Scheduled
  • OnDemand
Yanwen

No service levels for Yanwen.

Yodel

No service levels for Yodel.

Yun Express

No service levels for Yun Express.

GET /shipments/:id/rates

Regenerate Rates for a Shipment

You can update the Rates of a Shipment at any time. This operation respects the carrier_accounts attribute.

Regenerate Rates for Shipment Example


curl -X GET https://api.easypost.com/v2/shipments/shp_.../rates \
  -u <YOUR_TEST/PRODUCTION_API_KEY>:

{
  "id": "shp_vN9h7XLn",
  "object": "Shipment",
  "mode": "test",
  "to_address": {
    "id": "adr_zMlCRtmt",
    "object": "Address",
    "name": "Dr. Steve Brule",
    "company": null,
    "street1": "179 N Harbor Dr",
    "street2": null,
    "city": "Redondo Beach",
    "state": "CA",
    "zip": "90277",
    "country": "US",
    "phone": "4153334444",
    "mode": "test",
    "carrier_facility": null,
    "residential": null,
    "email": "dr_steve_brule@gmail.com",
    "created_at": "2013-04-22T05:39:56Z",
    "updated_at": "2013-04-22T05:39:56Z"
  },
  "from_address": {
    "id": "adr_VgoLT6Ex",
    "object": "Address",
    "name": "EasyPost",
    "company": null,
    "street1": "417 Montgomery Street",
    "street2": "5th Floor",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94104",
    "country": "US",
    "phone": "4153334444",
    "email": "support@easypost.com",
    "mode": "test",
    "carrier_facility": null,
    "residential": null,
    "created_at": "2013-04-22T05:39:57Z",
    "updated_at": "2013-04-22T05:39:57Z"
  },
  "parcel": {
    "id": "prcl_SI55pjx8",
    "object": "Parcel",
    "length": 20.2,
    "width": 10.9,
    "height": 5.0,
    "predefined_package": null,
    "weight": 140.8,
    "created_at": "2013-04-22T05:39:57Z",
    "updated_at": "2013-04-22T05:39:57Z"
  },
  "customs_info": {
    "id": "cstinfo_iNAizey5",
    "object": "CustomsInfo",
    "created_at": "2013-04-22T05:39:57Z",
    "updated_at": "2013-04-22T05:39:57Z",
    "contents_explanation": null,
    "contents_type": "merchandise",
    "customs_certify": false,
    "customs_signer": null,
    "eel_pfc": null,
    "non_delivery_option": "return",
    "restriction_comments": null,
    "restriction_type": "none",
    "customs_items": [
      {
        "id": "cstitem_9eDIbaDR",
        "object": "CustomsItem",
        "description": "Many, many EasyPost stickers.",
        "hs_tariff_number": "123456",
        "origin_country": "US",
        "quantity": 1,
        "value": 879,
        "weight": 140,
        "created_at": "2013-04-22T05:39:57Z",
        "updated_at": "2013-04-22T05:39:57Z"
      }
    ]
  },
  "rates": [
    {
      "id": "rate_nyCb6ubX",
      "object": "Rate",
      "carrier_account_id": "ca_12345678",
      "service": "FirstClassPackageInternationalService",
      "rate": "9.50",
      "carrier": "USPS",
      "shipment_id": "shp_vN9h7XLn",
      "delivery_days": 4,
      "delivery_date": "2013-04-26T05:40:57Z",
      "delivery_date_guaranteed": false,
      "created_at": "2013-04-22T05:40:57Z",
      "updated_at": "2013-04-22T05:40:57Z"
    }, {
      "id": "rate_uJh8iO2n",
      "object": "Rate",
      "carrier_account_id": "ca_12345678",
      "service": "PriorityMailInternational",
      "rate": "27.40",
      "carrier": "USPS",
      "shipment_id": "shp_vN9h7XLn",
      "delivery_days": 2,
      "delivery_date": "2013-04-24T05:40:57Z",
      "delivery_date_guaranteed": false,
      "created_at": "2013-04-22T05:40:57Z",
      "updated_at": "2013-04-22T05:40:57Z"
    }, {
      "id": "rate_oZqapNpE",
      "object": "Rate",
      "carrier_account_id": "ca_12345678",
      "service": "ExpressMailInternational",
      "rate": "35.48",
      "carrier": "USPS",
      "shipment_id": "shp_vN9h7XLn",
      "delivery_days": 1,
      "delivery_date": "2013-04-23T05:40:57Z",
      "delivery_date_guaranteed": true,
      "created_at": "2013-04-22T05:40:57Z",
      "updated_at": "2013-04-22T05:40:57Z"
    }
  ],
  "scan_form": null,
  "selected_rate": null,
  "postage_label": null,
  "tracking_code": null,
  "refund_status": null,
  "insurance": null,
  "created_at": "2013-04-22T05:40:57Z",
  "updated_at": "2013-04-22T05:40:57Z"
}

Messages

When rating a Shipment or Pickup, some carriers may fail to generate rates. These failures are returned as part of the Shipment or Pickup as part of their messages attribute, and follow a common object structure.

It is important to note that the message value for any member of this list comes directly from the carrier, not from EasyPost. This means that if you see an authentication or other non-shipping error here, it is not an issue between you and EasyPost, it is an issue between you and the carrier, or an issue with the given data.

Message Object

attribute type specification
carrier string the name of the carrier generating the error, e.g. "UPS"
type string the category of error that occurred. Most frequently "rate_error"
message string the string from the carrier explaining the problem.

Shipping Insurance

Insuring your Shipment is as simple as sending us the value of the contents. We charge 1% of the value, with a $1 minimum, and handle all the claims. All our claims are paid out within 30 days.

To buy insurance, first purchase the Shipment, then make the insurance call before the package begins being handled by the carrier.

POST /shipments/:id/insure
Insure Shipment Request Parameters
param example
amount 200.00

Insure Shipment Example


curl -X POST https://api.easypost.com/v2/shipments/shp_.../insure \
  -u <YOUR_TEST/PRODUCTION_API_KEY>: \
  -d 'amount=888.50'

{
  "id": "shp_vN9h7XLn",
  "object": "Shipment",
  "mode": "test",
  "insurance": "888.50",
  "to_address": {
    "id": "adr_zMlCRtmt",
    "object": "Address",
    "name": "Rob Ford",
    "company": null,
    "street1": "100 Queen St. West",
    "street2": null,
    "city": "Toronto",
    "state": "ON",
    "zip": "M5H2N2",
    "country": "CA",
    "phone": "4163334444",
    "email": null,
    "created_at": "2013-04-22T05:39:56Z",
    "updated_at": "2013-04-22T05:39:56Z"
  },
  "from_address": {
    "id": "adr_VgoLT6Ex",
    "object": "Address",
    "name": "EasyPost",
    "company": null,
    "street1": "417 Montgomery Street",
    "street2": "5th Floor",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94104",
    "country": "US",
    "phone": "4153334444",
    "email": "support@easypost.com",
    "created_at": "2013-04-22T05:39:57Z",
    "updated_at": "2013-04-22T05:39:57Z"
  },
  "parcel": {
    "id": "prcl_SI55pjx8",
    "object": "Parcel",
    "length": 20.2,
    "width": 10.9,
    "height": 5.0,
    "predefined_package": null,
    "weight": 140.8,
    "created_at": "2013-04-22T05:39:57Z",
    "updated_at": "2013-04-22T05:39:57Z"
  },
  "customs_info": {
    "id": "cstinfo_iNAizey5",
    "object": "CustomsInfo",
    "created_at": "2013-04-22T05:39:57Z",
    "updated_at": "2013-04-22T05:39:57Z",
    "contents_explanation": null,
    "contents_type": "merchandise",
    "customs_certify": false,
    "customs_signer": null,
    "eel_pfc": null,
    "non_delivery_option": "return",
    "restriction_comments": null,
    "restriction_type": "none",
    "customs_items": [
      {
        "id": "cstitem_9eDIbaDR",
        "object": "CustomsItem",
        "description": "Many, many EasyPost stickers.",
        "hs_tariff_number": "123456",
        "origin_country": "US",
        "quantity": 1,
        "value": 879,
        "weight": 140,
        "created_at": "2013-04-22T05:39:57Z",
        "updated_at": "2013-04-22T05:39:57Z"
      }
    ]
  },
  "rates": [
    {
      "id": "rate_oZqapNpE",
      "object": "Rate",
      "service": "ExpressMailInternational",
      "rate": "35.48",
      "carrier": "USPS",
      "shipment_id": "shp_vN9h7XLn",
      "created_at": "2013-04-22T05:40:57Z",
      "updated_at": "2013-04-22T05:40:57Z"
    }
  ],
  "scan_form": null,
  "selected_rate": null,
  "postage_label": null,
  "tracking_code": "",
  "refund_status": null,
  "created_at": "2013-04-22T05:40:57Z",
  "updated_at": "2013-04-22T05:40:57Z"
}

Refunds

USPS shipping labels can be refunded if requested within 30 days of generation. The processing time is 14 days, after which the funds will return to your EasyPost balance. EasyPost fees will also be refunded. To qualify, a shipment must not have been scanned by the USPS, or included on a Scan Form.

Refunds can be tracked through your Shipments Dashboard by requesting a CSV Report.

UPS and FedEx shipping labels may be refunded within 90 days of creation.

POST /shipments/:id/refund

Create a Refund

Refunding a Shipment is avaliable for many carriers supported by EasyPost. Once the refund has been submitted, refund_status attribute of the Shipment will be populated with one of the possible values: "submitted", "refunded", "rejected". The most common initial status is "submitted". Many carriers require that the refund be processed before the refund_status will move to "refunded". The length of this process depends on the carrier, but no greater than 30 days.

Refunds created very shortly after a label is generated may be improperly flagged as invalid, but you may retry a refund with the "rejected" status by submitting the same request again. Carriers that are bill-on-scan tend to have refunds attempts return as "not_applicable", which will not change with multiple retries.

Create Refund Example


curl -X GET https://api.easypost.com/v2/shipments/shp_.../refund \
  -u <YOUR_TEST/PRODUCTION_API_KEY>:

{
  "batch_message": null,
  "batch_status": null,
  "created_at": "2013-11-08T15:50:00Z",
  "customs_info": null,
  "from_address": {
    "city": "San Francisco",
    "company": null,
    "country": "US",
    "created_at": "2013-11-08T15:49:59Z",
    "email": null,
    "id": "adr_faGeob9S",
    "mode": "test",
    "name": "EasyPost",
    "object": "Address",
    "phone": "415-379-7678",
    "state": "CA",
    "street1": "417 Montgomery Street",
    "street2": "5th Floor",
    "updated_at": "2013-11-08T15:49:59Z",
    "zip": "94104"
  },
  "id": "shp_vN9h7XLn",
  "insurance": null,
  "is_return": false,
  "mode": "test",
  "object": "Shipment",
  "parcel": {
    "created_at": "2013-11-08T15:49:59Z",
    "height": null,
    "id": "prcl_TXCreKJp",
    "length": null,
    "mode": "test",
    "object": "Parcel",
    "predefined_package": "UPSLetter",
    "updated_at": "2013-11-08T15:49:59Z",
    "weight": 3.0,
    "width": null
  },
  "postage_label": {
    "created_at": "2013-11-08T20:57:32Z",
    "id": "pl_2Np7asmw",
    "integrated_form": "none",
    "label_date": "2013-11-08T20:57:32Z",
    "label_epl2_url": null,
    "label_file_type": "image/png",
    "label_pdf_url": "http://assets.geteasypost.com/postage_labels/label_pdfs/Z7t7o2.pdf",
    "label_resolution": 200,
    "label_size": "4x7",
    "label_type": "default",
    "label_url": "http://assets.geteasypost.com/postage_labels/labels/lUoagDx.png",
    "label_zpl_url": "http://assets.geteasypost.com/postage_labels/label_zpls/GG0F5F.zpl",
    "object": "PostageLabel",
    "updated_at": "2013-11-08T21:11:14Z"
  },
  "rates": [
    {
      "carrier": "UPS",
      "created_at": "2013-11-08T15:50:02Z",
      "currency": "USD",
      "id": "rate_vWwNuK8z",
      "object": "Rate",
      "rate": "30.44",
      "service": "NextDayAir",
      "shipment_id": "shp_w1xi76n4",
      "updated_at": "2013-11-08T15:50:02Z"
    }, {
      "carrier": "UPS",
      "created_at": "2013-11-08T15:50:02Z",
      "currency": "USD",
      "id": "rate_kqsS35Cx",
      "object": "Rate",
      "rate": "60.28",
      "service": "NextDayAirEarlyAM",
      "shipment_id": "shp_w1xi76n4",
      "updated_at": "2013-11-08T15:50:02Z"
    }
  ],
  "reference": null,
  "refund_status": "submitted",
  "scan_form": null,
  "selected_rate": {
    "carrier": "UPS",
    "created_at": "2013-11-08T15:50:02Z",
    "currency": "USD",
    "id": "rate_vWwNuK8z",
    "object": "Rate",
    "rate": "30.44",
    "service": "NextDayAir",
    "shipment_id": "shp_w1xi76n4",
    "updated_at": "2013-11-08T15:50:02Z"
  },
  "status": "unknown",
  "to_address": {
    "city": "Redondo Beach",
    "company": null,
    "country": "US",
    "created_at": "2013-11-08T15:49:58Z",
    "email": "dr_steve_brule@gmail.com",
    "id": "adr_EyDCpoii",
    "mode": "test",
    "name": "Dr. Steve Brule",
    "object": "Address",
    "phone": null,
    "state": "CA",
    "street1": "179 N Harbor Dr",
    "street2": null,
    "updated_at": "2013-11-08T15:49:58Z",
    "zip": "90277"
  },
  "tracker": {
    "created_at": "2013-11-08T20:57:32Z",
    "id": "trk_k7oNSa1Q",
    "mode": "test",
    "object": "Tracker",
    "shipment_id": "shp_w1xi76n4",
    "status": "unknown",
    "tracking_code": "1ZE6A4850190733810",
    "tracking_details": [ ],
    "updated_at": "2013-11-08T20:58:26Z"
  },
  "tracking_code": "1ZE6A4850190733810",
  "updated_at": "2013-11-08T20:58:26Z"
}

Returns

If you are shipping merchandise or other frequently-returned products, you may wish to generate return labels to include with your shipment, for you customer's convenience. EasyPost offers a simple way to submit the same parameters as your initial shipment, but with an additional flag set, that will generate you a return label to receive any return shipments at your original from address.

It's important for some carriers, with different return billing, to specify a return label even if it's not a return label for an earlier Shipment.

If doing more than 10,000 USPS Returns in a year, please contact EasyPost for the USPS scan-based return program, which we also offer.

POST /shipments

Create a Return Shipment

You can easily create return labels. All you need to do is set the is_return parameter to "true", leave the addresses the same as the initial Shipment's creation request and we switch the To and From Addresses for the return Shipment.

param example
is_return true
to_address the original Shipment's to_address
from_address the original Shipment's from_address

Create Return Shipment Example


curl -X POST https://api.easypost.com/v2/shipments \
  -u <YOUR_TEST/PRODUCTION_API_KEY>: \
  -d 'shipment[to_address][id]=adr_...' \
  -d 'shipment[from_address][id]=adr_...' \
  -d 'shipment[parcel][id]=prcl_...' \
  -d 'shipment[is_return]=true'

{
  "id": "shp_vN9h7XLn",
  "object": "Shipment",
  "mode": "test",
  "to_address": {
    "id": "adr_zMlCRtmt",
    "object": "Address",
    "name": "Rob Ford",
    "company": null,
    "street1": "100 Queen St. West",
    "street2": null,
    "city": "Toronto",
    "state": "ON",
    "zip": "M5H2N2",
    "country": "CA",
    "phone": "4163334444",
    "email": null,
    "created_at": "2013-04-22T05:39:56Z",
    "updated_at": "2013-04-22T05:39:56Z"
  },
  "from_address": {
    "id": "adr_VgoLT6Ex",
    "object": "Address",
    "name": "EasyPost",
    "company": null,
    "street1": "417 Montgomery Street",
    "street2": "5th Floor",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94104",
    "country": "US",
    "phone": "4154567890",
    "email": null,
    "created_at": "2013-04-22T05:39:57Z",
    "updated_at": "2013-04-22T05:39:57Z"
  },
  "parcel": {
    "id": "prcl_SI55pjx8",
    "object": "Parcel",
    "length": 20.2,
    "width": 10.9,
    "height": 5.0,
    "predefined_package": null,
    "weight": 140.8,
    "created_at": "2013-04-22T05:39:57Z",
    "updated_at": "2013-04-22T05:39:57Z"
  },
  "customs_info": null
  "rates": [
    {
      "id": "rate_oZqapNpE",
      "object": "Rate",
      "service": "ExpressMailInternational",
      "rate": "35.48",
      "carrier": "USPS",
      "shipment_id": "shp_vN9h7XLn",
      "created_at": "2013-04-22T05:40:57Z",
      "updated_at": "2013-04-22T05:40:57Z"
    }, {
      "id": "rate_Dc5Q9Zfo",
      "object": "Rate",
      "service": "GXG",
      "rate": "55.41",
      "carrier": "USPS",
      "shipment_id": "shp_vN9h7XLn",
      "created_at": "2013-04-22T05:40:57Z",
      "updated_at": "2013-04-22T05:40:57Z"
    }
  ],
  "scan_form": null,
  "selected_rate": null,
  "postage_label": null,
  "is_return": true,
  "tracking_code": null,
  "refund_status": null,
  "insurance": null,
  "created_at": "2013-04-22T05:40:57Z",
  "updated_at": "2013-04-22T05:40:57Z"
}

Tracking

A Tracker object contains all of the tracking information for a package. A Tracker is created automatically whenever you buy a Shipment through EasyPost; if you don’t use EasyPost to purchase your shipping labels, you can still track packages through our API by creating a Tracker object directly. Each Tracker is continually updated in the background as the package moves through its life cycle, regardless of whether or not the label was purchased through EasyPost.

After creation, a Tracker object will be updated periodically based on when the carrier provides EasyPost with new tracking information. This information can be consumed by using our webhooks infrastructure. Every time a Tracker is updated a webhook Event will be sent.

The Tracker object contains both the current information about the package as well as previous updates. All of the previous updates are stored in the tracking_details array. Each TrackingDetail object contains the status, the message from the carrier, and a TrackingLocation.

The TrackingLocation contains city, state, country, and zip information about the location where the package was scanned. The information each carrier provides is different, so some carriers may not make use of all of these fields.

Some Tracker objects may also contain a CarrierDetail, which stores some additional information about the Tracker that the carrier has made available to EasyPost. The CarrierDetail object contains the service and container_type of the package. Additionally, it also stores the est_delivery_date_local and est_delivery_time_local, which provide information about the local delivery time.

It's worth noting that tracking_codes are not globally unique. Each carrier promises uniqueness for a given tracking_code for a certain period of time, but the length of time varies greatly based on the specific carrier and service level. The carriers do eventually recycle tracking_codes, and for this reason enforcing uniqueness on the tracking_code field is not recommended. EasyPost does, however, prevent the creation of duplicate Trackers based on tracking_code and carrier; duplicate requests by the same User will simply return the original Tracker.

Tracker Object

attribute type specification
id string Unique identifier, begins with "trk_"
object string "Tracker"
mode string "test" or "production"
tracking_code string The tracking code provided by the carrier
status string The current status of the package, possible values are "unknown", "pre_transit", "in_transit", "out_for_delivery", "delivered", "available_for_pickup", "return_to_sender", "failure", "cancelled" or "error"
signed_by string The name of the person who signed for the package (if available)
weight float The weight of the package as measured by the carrier in ounces (if available)
est_delivery_date datetime The estimated delivery date provided by the carrier (if available)
shipment_id string The id of the EasyPost Shipment object associated with the Tracker (if any)
carrier string The name of the carrier handling the shipment
tracking_details TrackingDetail array Array of the associated TrackingDetail objects
carrier_detail CarrierDetail The associated CarrierDetail object (if available)
fees Fee array Array of the associated Fee objects
created_at datetime
updated_at datetime

TrackingDetail Object

attribute type specification
object string "TrackingDetail"
message string Description of the scan event
status string Status of the package at the time of the scan event, possible values are "unknown", "pre_transit", "in_transit", "out_for_delivery", "delivered", "available_for_pickup", "return_to_sender", "failure", "cancelled" or "error"
datetime datetime The timestamp when the tracking scan occurred
source string The original source of the information for this scan event, usually the carrier
tracking_location TrackingLocation The location associated with the scan event

TrackingLocation Object

attribute type specification
object string "TrackingLocation"
city string The city where the scan event occurred (if available)
state string The state where the scan event occurred (if available)
country string The country where the scan event occurred (if available)
zip string The postal code where the scan event occurred (if available)

CarrierDetail Object

attribute type specification
object string "CarrierDetail"
service string The service level the associated shipment was shipped with (if available)
container_type string The type of container the associated shipment was shipped in (if available)
est_delivery_date_local date The estimated delivery date as provided by the carrier, in the local time zone (if available)
est_delivery_time_local time The estimated delivery time as provided by the carrier, in the local time zone (if available)

Testing Specific Tracking States

Sometimes you may want to simulate specific tracking statuses (e.g. "out_for_delivery") within your application to test how your application responds. EasyPost has a set of test tracking_codes that, when sent to the API, respond with specific tracking statuses and send a webhook Event to your test mode URL. The tracking updates that are sent by these tracking_codes will contain canned information, but it will be similar in form to the information normally provided by the carrier you selected.

Test Tracking Codes

tracking_code status
EZ1000000001 pre_transit
EZ2000000002 in_transit
EZ3000000003 out_for_delivery
EZ4000000004 delivered
EZ5000000005 return_to_sender
EZ6000000006 failure
EZ7000000007 unknown

Carrier Tracking Strings

Carrier String Representation
Aramex Aramex
Asendia Asendia
Australia Post AustraliaPost
Bluedart BlueDart
Boxberry Boxberry
Cainiao Cainiao
Canada Post CanadaPost
Canpar Canpar
China Post ChinaPost
Chronopost Chronopost
Colis Privé ColisPrive
Colissimo Colissimo
Correios Correios
DHL Express DHLExpress
DHL Freight DHLFreight
DHL Germany DHLGermany
DHL Global Mail DHLGlobalMail
DPD DPD
Delhivery Delhivery
Deliv Deliv
Deutsche Post DeutschePost
Direct Link DirectLink
EC Firstclass ECFirstclass
EMS ChinaEMS
Ecom Express EcomExpress
Fastway Fastway
FedEx FedEx
FedEx Mailview FedExMailview
FedEx SmartPost FedexSmartPost
FedEx UK FedExUK
Flyt Express FlytExpress
GLS GLS
GSO GSO
Hong Kong Post HongKongPost
IMEX IMEX
India Post IndiaPost
Interlink Express InterlinkExpress
JP Post JPPost
LSO LSO
La Poste LaPoste
LaserShip LaserShip
Nanjing Woyuan NanjingWoyuan
New Zealand Post NewZealandPost
Norco Norco
Nova Poshta NovaPoshta
OnTrac OnTrac
OnTrac DirectPost OnTracDirectPost
POS Malaysia POSMalaysia
Parcelforce Parcelforce
PostNL PostNL
PostNord PostNord
Postmates Postmates
Purolator Purolator
R+L Carriers RLCarriers
Royal Mail RoyalMail
SMSA Express SMSAExpress
Spee-Dee SpeeDee
TNT Express TNTExpress
UPS UPS
UPS Mail Innovations UPSMailInnovations
USPS USPS
Uber RUSH UberRUSH
Yanwen Yanwen
Yodel Yodel
Yun Express YunExpress
POST /trackers

Create a Tracker

A Tracker can be created with only a tracking_code. Optionally, you can provide the carrier parameter, which indicates the carrier the package was shipped with. If no carrier is provided, EasyPost will attempt to determine the carrier based on the tracking_code provided. Providing a carrier parameter is recommended, since some tracking_codes are ambiguous and may match with more than one carrier. In addition, not having to auto-match the carrier will significantly speed up the response time.

In an effort to reduce wasted resources, EasyPost prevents the creation of duplicate Trackers. A Tracker is considered to be a duplicate if another Tracker with the same tracking_code and carrier was created by the same User in the last three months. In the case where a duplicate request is submitted, the original Tracker will be returned.

Create Tracker Request Parameters
param example info
tracking_code 9400110898825022579493 The tracking code associated with the package you'd like to track
carrier USPS The carrier associated with the tracking_code you provided. The carrier will get auto-detected if none is provided

Create Tracker Example


curl -X POST https://api.easypost.com/v2/trackers \
  -u <YOUR_TEST/PRODUCTION_API_KEY>: \
  -d 'tracker[tracking_code]=9400110898825022579493' \
  -d 'tracker[carrier]=USPS'

{
  "id": "trk_c8e0edb5bb284caa934a0d3db23a148z",
  "object": "Tracker",
  "mode": "test",
  "tracking_code": "9400110898825022579493",
  "status": "in_transit",
  "created_at": "2016-01-13T21:52:28Z",
  "updated_at": "2016-01-13T21:52:32Z",
  "signed_by": null,
  "weight": null,
  "est_delivery_date": null,
  "shipment_id": null,
  "carrier": "USPS",
  "tracking_details": [
    {
      "object": "TrackingDetail",
      "message": "Shipping Label Created",
      "status": "pre_transit",
      "datetime": "2015-12-31T15:58:00Z",
      "source": "USPS",
      "tracking_location": {
        "object": "TrackingLocation",
        "city": "FOUNTAIN VALLEY",
        "state": "CA",
        "country": null,
        "zip": "92708"
      }
    },
    {
      "object": "TrackingDetail",
      "message": "Arrived at Post Office",
      "status": "in_transit",
      "datetime": "2016-01-07T06:58:00Z",
      "source": "USPS",
      "tracking_location": {
        "object": "TrackingLocation",
        "city": "FOUNTAIN VALLEY",
        "state": "CA",
        "country": null,
        "zip": "92728"
      }
    }
  ],
  "carrier_detail": null,
  "fees": [
    {
      "object": "Fee",
      "type": "TrackerFee",
      "amount": "0.00000",
      "charged": true,
      "refunded": false
    }
  ]
}
GET /trackers

Retrieve a List of Trackers

The Tracker List is a paginated list of all Tracker objects associated with the given API Key. It accepts a variety of parameters which can be used to modify the scope. The has_more attribute indicates whether or not there are additional pages be requested. The recommended way of paginating is to use either the before_id or after_id parameter to specify where the next page begins.

Using the Tracker List endpoint is the recommended way of retrieving a Tracker by tracking_code or carrier. Unlike the retrieving a Tracker using the Retrieve endpoint, which accepts an id, the List endpoint accepts the tracking_code as the search parameter. Normally, you'll only have one Tracker with a given tracking_code, but it is also possible to further filter those results by including the carrier parameter in your request.

Retrieve a List Tracker Request Parameters
param example info
before_id trk_c8e0edb5bb284c Optional pagination parameter. Only trackers created before the given ID will be included. May not be used with after_id
after_id trk_c8e0edb5bb284c Optional pagination parameter. Only trackers created after the given ID will be included. May not be used with before_id
start_datetime 2016-01-02T00:00:00Z Only return Trackers created after this timestamp. Defaults to 1 month ago, or 1 month before a passed end_datetime
end_datetime 2016-01-02T00:00:00Z Only return Trackers created before this timestamp. Defaults to end of the current day, or 1 month after a passed start_datetime
page_size 30 The number of Trackers to return on each page. The maximum value is 100
tracking_code 9400110898825022579493 Only returns Trackers with the given tracking_code. Useful for retrieving an individual Tracker by tracking_code rather than by ID
carrier USPS Only returns Trackers with the given carrier value

Retrieve a List Trackers Example


curl -X GET https://api.easypost.com/v2/trackers \
  -u <YOUR_TEST/PRODUCTION_API_KEY>: \
  -d 'page_size=2' \
  -d 'start_datetime=2016-01-02T08:50:00Z'

{
  "trackers": [
    {
      "id": "trk_c8e0edb5bb284caa934a0d3db23a148z",
      "object": "Tracker",
      "mode": "test",
      "tracking_code": "9400110898825022579493",
      "status": "in_transit",
      "created_at": "2016-01-13T21:52:28Z",
      "updated_at": "2016-01-13T21:52:32Z",
      "signed_by": null,
      "weight": null,
      "est_delivery_date": null,
      "shipment_id": null,
      "carrier": "USPS",
      "tracking_details": [
        {
          "object": "TrackingDetail",
          "message": "Shipping Label Created",
          "status": "pre_transit",
          "datetime": "2015-12-31T15:58:00Z",
          "source": "USPS",
          "tracking_location": {
            "object": "TrackingLocation",
            "city": "FOUNTAIN VALLEY",
            "state": "CA",
            "country": null,
            "zip": "92708"
          }
        },
        {
          "object": "TrackingDetail",
          "message": "Arrived at Post Office",
          "status": "in_transit",
          "datetime": "2016-01-07T06:58:00Z",
          "source": "USPS",
          "tracking_location": {
            "object": "TrackingLocation",
            "city": "FOUNTAIN VALLEY",
            "state": "CA",
            "country": null,
            "zip": "92728"
          }
        }
      ],
      "carrier_detail": null,
      "fees": [
        {
          "object": "Fee",
          "type": "TrackerFee",
          "amount": "0.00000",
          "charged": true,
          "refunded": false
        }
      ]
    },
    {
      "id": "trk_bae2066ac16e45dba07b7c08baf10bc9",
      "object": "Tracker",
      "mode": "test",
      "tracking_code": "JW061221982GB",
      "status": "unknown",
      "created_at": "2016-01-20T19:22:26Z",
      "updated_at": "2016-01-20T19:22:29Z",
      "signed_by": null,
      "weight": null,
      "est_delivery_date": null,
      "shipment_id": null,
      "carrier": "RoyalMail",
      "tracking_details": [],
      "carrier_detail": null,
      "fees": [{
        "object": "Fee",
        "type": "TrackerFee",
        "amount": "0.00000",
        "charged": true,
        "refunded": false
      }]
    }
  ],
  "has_more": true
}
GET /trackers/:id

Retrieve a Tracker

Retrieve a Tracker by id.

Retrieve Tracker Request Parameters
param example info
id trk_c8e0edb5bb284caa9 Unique, starts with "trk_"

Retrieve Tracker Example


curl -X GET https://easypost.com/api/v2/trackers/trk_... \
  -u <YOUR_TEST/PRODUCTION_API_KEY>:

{
  "id": "trk_c8e0edb5bb284caa934a0d3db23a148z",
  "object": "Tracker",
  "mode": "test",
  "tracking_code": "9400110898825022579493",
  "status": "in_transit",
  "created_at": "2016-01-13T21:52:28Z",
  "updated_at": "2016-01-15T20:56:56Z",
  "signed_by": null,
  "weight": null,
  "est_delivery_date": null,
  "shipment_id": null,
  "carrier": "USPS",
  "tracking_details": [
    {
      "object": "TrackingDetail",
      "message": "Shipping Label Created",
      "status": "pre_transit",
      "datetime": "2015-12-31T15:58:00Z",
      "source": "USPS",
      "tracking_location": {
        "object": "TrackingLocation",
        "city": "FOUNTAIN VALLEY",
        "state": "CA",
        "country": null,
        "zip": "92708"
      }
    },
    {
      "object": "TrackingDetail",
      "message": "Arrived at Post Office",
      "status": "in_transit",
      "datetime": "2016-01-07T06:58:00Z",
      "source": "USPS",
      "tracking_location": {
        "object": "TrackingLocation",
        "city": "FOUNTAIN VALLEY",
        "state": "CA",
        "country": null,
        "zip": "92728"
      }
    }
  ],
  "carrier_detail": null,
  "fees": [
    {
      "object": "Fee",
      "type": "TrackerFee",
      "amount": "0.00000",
      "charged": true,
      "refunded": false
    }
  ]
}

Batches

The Batch object allows you to perform operations on multiple Shipments at once. This includes scheduling a Pickup, creating a ScanForm and consolidating labels. Operations performed on Batches are asynchronous and take advantage of our webhoook infrastructure.

Batch Object

attribute type specification
id string Unique, begins with "batch_"
reference string An optional field that may be used in place of ID in some API endpoints
object string "Batch"
mode string "test" or "production"
state string The overall state. Possible values are "creating", "creation_failed", "created", "purchasing", "purchase_failed", "purchased", "label_generating", and "label_generated"
num_shipments integer The number of shipments added
shipments BatchShipment array
status object A map of BatchShipment statuses to the count of BatchShipments with that status. Valid statuses are "postage_purchased", "postage_purchase_failed", "queued_for_purchase", and "creation_failed"
label_url string The label image url
scan_form ScanForm The created ScanForm
pickup Pickup The created Pickup
created_at datetime
updated_at datetime

BatchShipment Object

attribute type specification
id string The id of the Shipment. Unique, begins with "shp_"
reference string An optional field that may be used in place of ID in some API endpoints
batch_status string The current status. Possible values are "postage_purchased", "postage_purchase_failed", "queued_for_purchase", and "creation_failed"
batch_message string A human readable message for any errors that occurred during the Batch's life cycle
POST /batches

Create a Batch

A Batch can be created with or without Shipments. When created with Shipments the initial state will be creating. Once the state changes to created a webhook Event will be sent. When created with no Shipments the initial state will be created and webhook will be sent.

Create Batch Example


curl -X POST https://api.easypost.com/v2/batches \
  -u <YOUR_TEST/PRODUCTION_API_KEY>: \
  -d "batch[shipments][0][id]=shp_..."

{
  "id": "batch_...",
  "label_url": null,
  "mode": "test",
  "num_shipments": 1,
  "object": "Batch",
  "reference": null,
  "scan_form": null,
  "shipments": [
    {
      "id": "shp_...",
      "batch_status": "postage_purchased",
      "batch_message": null,
      "reference": null
    }
  ],
  "state": "created",
  "status": {
    "created": 0,
    "queued_for_purchase": 0,
    "creation_failed": 0,
    "postage_purchased": 0,
    "postage_purchase_failed": 0
  },
  "label_url": null,
  "created_at": "2014-07-22T07:34:39Z",
  "updated_at": "2014-07-22T07:34:39Z"
}
POST /batches/:id/add_shipments

Add Shipments to a Batch

Shipments can be added to a Batch throughout its life cycle. Just remember that the state change of a Batch is asynchronous and will fire a webhook Event when the state change is completed.

Add Shipments to Batch Request Parameters
param example
shipments [<Shipment>,<Shipment>,...]

Add Shipments to Batch Example


curl -X POST https://api.easypost.com/v2/batches/batch_.../add_shipments \
  -u <YOUR_TEST/PRODUCTION_API_KEY>: \
  -d 'batch[shipments][0][id]=shp_...' \
  -d 'batch[shipments][1][id]=shp_...' \
  ...

{
  "id": "batch_...",
  "label_url": null,
  "mode": "test",
  "num_shipments": 5,
  "object": "Batch",
  "reference": null,
  "scan_form": null,
  "shipments": [
    ....
  ],
  "state": "creating",
  "status": {
    "created": 0,
    "queued_for_purchase": 0,
    "creation_failed": 0,
    "postage_purchased": 5,
    "postage_purchase_failed": 0
  },
  "label_url": null,
  "created_at": "2014-07-22T07:34:39Z",
  "updated_at": "2014-07-22T07:34:39Z"
}
POST /batches/:id/remove_shipments

Remove Shipments from a Batch

There could be times when a Shipment needs to be removed from the Batch during its life cycle. Removing a Shipment does not remove it from the consolidated label or ScanForm.

param example
shipments [<Shipment>,<Shipment>,...]

Remove shipments from Batch Example


curl -X POST https://api.easypost.com/v2/batches/batch_.../remove_shipments \
  -u <YOUR_TEST/PRODUCTION_API_KEY>: \
  -d 'batch[shipments][0][id]=shp_...' \
  ...

{
  "id": "batch_...",
  "label_url": null,
  "mode": "test",
  "num_shipments": 1,
  "object": "Batch",
  "reference": null,
  "scan_form": null,
  "shipments": [
    {
      "id": "shp_...",
      "batch_status": "postage_purchased",
      "batch_message": null
    },
  ],
  "state": "creating",
  "status": {
    "created": 0,
    "queued_for_purchase": 0,
    "creation_failed": 0,
    "postage_purchased": 1,
    "postage_purchase_failed": 0
  },
  "label_url": null,
  "created_at": "2014-07-22T07:34:39Z",
  "updated_at": "2014-07-22T07:34:39Z"
}
POST /batches/:id/label

Batch Labels

One of the advantages of processing Shipments in batches is the ability to consolidate the PostageLabel into one file. This can only be done once for each batch and all Shipments must have a status of postage_purchased.

Available label formats are 'pdf', 'zpl' or 'epl2' format. Like converting a PostageLabel format, if this process will change the format of the labels they must have been created as PNGs.

param example
file_format ZPL

Generate label for Batch Example


curl -X POST https://api.easypost.com/v2/batches/batch_.../label \
  -u <YOUR_TEST/PRODUCTION_API_KEY>: \
  -d 'file_format=epl2'

{
  "id": "batch_...",
  "label_url": null,
  "mode": "test",
  "num_shipments": 4,
  "object": "Batch",
  "reference": null,
  "scan_form": null,
  "shipments": [
    ....
  ],
  "state": "creating",
  "status": {
    "created": 0,
    "queued_for_purchase": 0,
    "creation_failed": 0,
    "postage_purchased": 4,
    "postage_purchase_failed": 0
  },
  "label_url": null,
  "created_at": "2014-07-22T07:34:39Z",
  "updated_at": "2014-07-22T07:34:39Z"
}
POST /batches/:id/scan_form

Manifesting (SCAN Form)

A ScanForm can be created to speed up and simplify the carrier pickup process. The ScanForm is one document that can be scanned to mark all included tracking codes as "Accepted for Shipment" by the carrier. The following criteria must met before creation:

  • Refunded Shipments cannot be added.
  • Each Shipment must have the same origin address.
  • Shipments must all be dated (using the label_date option) on or after the date the form is generated.
  • Shipments cannot be added to more than one ScanForm.

ScanForm Object

attribute type specification
id string Unique, begins with "sf_"
object string "ScanForm"
status string Current status. Possible values are "creating", "created" and "failed"
message string Human readable message explaining any failures
address Address Address the will be Shipments shipped from
tracking_codes string array Tracking codes included on the ScanForm
form_url string Url of the document
form_file_type string File format of the document
batch_id string The id of the associated Batch. Unique, starts with "batch_"
created_at datetime
updated_at datetime

Generate manifest for Batch Example


curl -X POST https://api.easypost.com/v2/batches/batch_.../scan_form \
  -u <YOUR_TEST/PRODUCTION_API_KEY>:

# webhook will be sent to indicate the scan form was created

{
  "id": "batch_...",
  "label_url": null,
  "mode": "test",
  "num_shipments": 2,
  "object": "Batch",
  "reference": null,
  "scan_form": null,
  "shipments": [
    ....
  ],
  "state": "creating",
  "status": {
    "created": 2,
    "queued_for_purchase": 0,
    "creation_failed": 0,
    "postage_purchased": 0,
    "postage_purchase_failed": 0
  },
  "label_url": null,
  "created_at": "2014-07-22T07:34:39Z",
  "updated_at": "2014-07-22T07:34:39Z"
}

CustomsInfos

CustomsInfo objects contain CustomsItem objects and all necessary information for the generation of customs forms required for international shipping.

Please see the Shipments documentation for examples of including a CustomsInfo object in a shipment.

CustomsInfo Object

attribute type specification
id string Unique, begins with 'cstinfo_'
object string 'CustomsInfo'
eel_pfc string "EEL" or "PFC"
value less than $2500: "NOEEI 30.37(a)"; value greater than $2500: see Customs Guide
contents_type string "documents", "gift", "merchandise", "returned_goods", "sample", or "other"
contents_explanation string Human readable description of content. Required for certain carriers and always required if contents_type is "other"
customs_certify boolean Electronically certify the information provided
customs_signer string Required if customs_certify is true
non_delivery_option string "abandon" or "return", defaults to "return"
restriction_type string "none", "other", "quarantine", or "sanitary_phytosanitary_inspection"
restriction_comments string Required if restriction_type is not "none"
customs_items CustomItem array Describes to products being shipped
created_at datetime
updated_at datetime
POST /customs_infos

Create a CustomsInfo

A CustomsInfo object contains all administrative information for processing customs, as well as a list of CustomsItems. When creating a CustomsInfo, you may store the ID from the response for use later in shipment creation.

Create CustomsInfo Request Parameters
param example
customs_certify true
cutoms_signer "Steve Brule"
contents_type "merchandise"
restriction_type "none"
eel_pfc "NOEEI 30.37(a)"
customs_items [<CustomsItem>,<CustomsItem>,...]

Create CustomsInfo Example


curl -X POST https://api.easypost.com/v2/customs_infos \
  -u <YOUR_TEST/PRODUCTION_API_KEY>: \
  -d 'customs_info[customs_certify]=true' \
  -d 'customs_info[customs_signer]=Steve Brule' \
  -d 'customs_info[contents_type]=merchandise' \
  -d 'customs_info[contents_explanation]=' \
  -d 'customs_info[restriction_type]=none' \
  -d 'customs_info[eel_pfc]=NOEEI 30.37(a)' \
  -d 'customs_info[customs_items][0][id]=cstitem_...' \
  -d 'customs_info[customs_items][1][description]=Sweet shirts' \
  -d 'customs_info[customs_items][1][quantity]=2' \
  -d 'customs_info[customs_items][1][value]=23' \
  -d 'customs_info[customs_items][1][weight]=11' \
  -d 'customs_info[customs_items][1][hs_tariff_number]=654321' \
  -d 'customs_info[customs_items][1][origin_country]=US'

{
  "id": "cstinfo_zN5tbjEd",
  "object": "CustomsInfo",
  "contents_explanation": null,
  "contents_type": "merchandise",
  "customs_certify": true,
  "customs_signer": "Steve Brule",
  "eel_pfc": "NOEEI 30.37(a)",
  "non_delivery_option": "return",
  "restriction_comments": null,
  "restriction_type": "none",
  "customs_items": [{
      "id": "cstitem_OpPpXeny",
      "object": "CustomsItem",
      "description": "T-Shirt",
      "hs_tariff_number": "123456",
      "origin_country": "US",
      "quantity": 1,
      "value": 10,
      "weight": 5,
      "created_at": "2013-04-22T07:17:51Z",
      "updated_at": "2013-04-22T07:17:51Z"
    }, {
      "id": "cstitem_VklGOHPs",
      "object": "CustomsItem",
      "description": "Sweet shirts",
      "hs_tariff_number": "654321",
      "origin_country": "US",
      "quantity": 2,
      "value": 23,
      "weight": 11,
      "created_at": "2013-04-22T07:17:51Z",
      "updated_at": "2013-04-22T07:17:51Z"
    }
  ],
  "created_at": "2013-04-22T07:17:51Z",
  "updated_at": "2013-04-22T07:17:51Z"
}

CustomsItems

A CustomsItem object describes goods for international shipment and should be created then included in a CustomsInfo object.

CustomsItem Object

attribute type specification
id string Unique, begins with 'cstitem_'
object string 'CustomsItem'
description string Required, description of item being shipped
quantity float Required, greater than zero
value float (USD) Required, greater than zero, total value (unit value * quantity)
weight float (oz) Required, greater than zero, total weight (unit weight * quantity)
hs_tariff_number string Harmonized Tariff Schedule, e.g. "6109.10.0012" for Men's T-shirts
origin_country string Required, 2 char country code
currency string 3 char currency code, default USD
created_at datetime
updated_at datetime
POST /customs_items

Create a CustomsItem

A CustomsItem contains information relating to each product within the package. When creating a customs item, you may store the ID from the response for use later in CustomsInfo creation.

Create CustomsItem Request Parameters
param example
description "T-Shirt"
quantity 1
weight 5
value 10
hs_tariff_number "123456"
origin_country "US"

Create CustomsItem Example


curl -X POST https://api.easypost.com/v2/customs_items \
  -u <YOUR_TEST/PRODUCTION_API_KEY>: \
  -d 'customs_item[description]=T-shirt' \
  -d 'customs_item[quantity]=1' \
  -d 'customs_item[weight]=5' \
  -d 'customs_item[value]=10' \
  -d 'customs_item[hs_tariff_number]=123456' \
  -d 'customs_item[origin_country]=US'

{
  "id": "cstitem_LeWfJAV4",
  "object": "CustomsItem",
  "description": "T-shirt",
  "quantity": 1,
  "value": 10,
  "weight": 5,
  "hs_tariff_number": "123456",
  "origin_country": "US",
  "created_at": "2013-04-22T06:56:43Z",
  "updated_at": "2013-04-22T06:56:43Z"
}

Events

Webhook Events are triggered by changes in objects you've created via the API. Every time an Event related to one of your objects is created, EasyPost will send a POST request to each of the webhook URLs set up for your account. See the webhooks guide for more information.

Possible Event Types

A "tracker.updated" Event gets created whenever a Tracker object gets updated

A "batch.created" Event gets created when the initial creation of a Batch object is complete

A "batch.updated" Event gets created whenever the status of a Batch object changes

A "scan_form.created" Event gets created when the initial creation of a ScanForm object is complete

A "scan_form.updated" Event gets created whenever the status of a ScanForm object changes

Event Object

attribute type specification
object string "Event"
id string Unique identifier, begins with "evt_"
mode string "test" or "production"
description string Result type and event name, see the "Possible Event Types" section for more information
previous_attributes object Previous values of relevant result attributes
result object The object associated with the Event. See the "object" attribute on the result to determine its specific type
pending_urls string array Webhook URLs that have not yet been successfully notified as of the time this webhook event was sent. The URL receiving the Event will still be listed in pending_urls, as will any other URLs that receive the Event at the same time
completed_urls string array Webhook URLs that have already been successfully notified as of the time this webhook was sent
created_at datetime
updated_at datetime

Fees

Fee objects are used to represent the breakdown of charges made when purchasing an item on EasyPost. Shipments and Trackers both have associations to Fee objects.

Each Shipment object will have a Fee of type "LabelFee" to represent the five cents charged by EasyPost for the service. Shipments with postage collected by EasyPost (as opposed to shipments with postage collected directly by the carrier) will have a "PostageFee" according to the postage amount. Insurance on a Shipment will add an "InsuranceFee" with the insurance premium (not the covered value) for the amount. Tracker objects will have a "TrackerFee" with the price, even when a Tracker is free.

Fee Object

attribute type specification
object string "Fee"
type string The name of the category of fee. Possible types are "LabelFee", "PostageFee", "InsuranceFee", and "TrackerFee"
amount string USD value with sub-cent precision
charged boolean Whether EasyPost has successfully charged your account for the fee
refunded boolean Whether the Fee has been refunded successfully

Orders

The Order object represents a collection of packages and can be used for Multi-Piece Shipments. Like a single Shipment each Order consists of a "to" and "from" Address to be used for each Shipment within the Order. These Addresses will be copied to each Shipment so there is no need to specify them multiple times. Each Shipment must then specify its Parcel, Options, and CustomsInfo.

An Order created with valid Address and Shipment objects will automatically retrieve available shipping Rate options.

Order Object

attribute type specification
id string Unique, begins with "order_"
object string "Order"
reference string An optional field that may be used in place of id in other API endpoints
mode string "test" or "production"
to_address Address The destination address
from_address Address The origin address
return_address Address The shipper's address, defaults to from_address
buyer_address Address The buyer's address, defaults to to_address
shipments Shipment array All associated Shipment objects
rates Rate array All associated Rate objects
messages Message array Any carrier errors encountered during rating
is_return boolean Set true to create as a return
created_at datetime
updated_at datetime
POST /orders

Create an Order

An Order is almost exclusively a container for other objects, and thus an Order may reuse many of these objects. Alternatively, all the objects contained within an Order may be created at the same time.

You can limit the CarrierAccounts to use for rating by passing the carrier_accounts parameter.

Create Order Request Parameters
param example
reference "my-reference"
to_address <Address>
from_address <Address>
shipments [<Shipment>, <Shipment>, ...]
carrier_accounts [{"id": "ca_f02596dcabbb46a8ba823280efc277bb"}, ...]

Create Order Example


curl -X POST https://api.easypost.com/v2/orders \
  -u <YOUR_TEST/PRODUCTION_API_KEY>: \
  -d "order[to_address][id]=adr_..." \
  -d "order[from_address][id]=adr_..." \
  -d "order[shipments][0][parcel][predefined_package]=FedExBox" \
  -d "order[shipments][0][parcel][weight]=10.2" \
  -d "order[shipments][1][parcel][predefined_package]=FedExBox" \
  -d "order[shipments][1][parcel][weight]=17.5"

{
  "id": "order_b39d44e7059a46c8a787174e8320bf1c",
  "mode": "test",
  "reference": null,
  "is_return": false,
  "options": {"currency": "USD","label_date": null},
  "messages": [],
  "created_at": "2016-02-17T02:51:04Z",
  "updated_at": "2016-02-17T02:51:04Z",
  "customs_info": null,
  "to_address": { ... },
  "from_address": { ... },
  "buyer_address": { ... },
  "return_address": { ... },
  "items": [],
  "containers": [],
  "shipments": [
    {
      "id": "shp_7a387659db374a8ea197d7bba3009d5d",
      "created_at": "2016-02-17T02:51:04Z",
      "updated_at": "2016-02-17T02:51:10Z",
      "is_return": false,
      "messages": [],
      "mode": "test",
      "options": {"currency": "USD", "label_date": null},
      "reference": null,
      "status": "unknown",
      "tracking_code": null,
      "batch_id": null,
      "batch_status": null,
      "batch_message": null,
      "parcel": {
        "id": "prcl_071994637e1046ab98a79f96d8b26488",
        "object": "Parcel",
        "length": 20.2,
        "width": 10.9,
        "height": 5.0,
        "predefined_package": null,
        "weight": 17.5,
        "created_at": "2013-04-22T05:39:57Z",
        "updated_at": "2013-04-22T05:39:57Z"
      },
      "customs_info": null,
      "to_address": { ... },
      "from_address": { ... },
      "buyer_address": { ... },
      "return_address": { ... },
      "postage_label": null,
      "rates": [
        {
          "id": "rate_1f168714581b40af965dd740ddf35f69",
          "object": "Rate",
          "created_at": null,
          "updated_at": null,
          "mode": "test",
          "service": "PRIORITY_OVERNIGHT",
          "carrier": "FedEx",
          "rate": "47.36",
          "currency": "USD",
          "retail_rate": null,
          "retail_currency": null,
          "list_rate": null,
          "list_currency": null,
          "delivery_days": 1,
          "delivery_date": "2016-02-18T10:30:00Z",
          "delivery_date_guaranteed": true,
          "est_delivery_days": null,
          "shipment_id": "shp_b701a9da21424a5f85a09530c9f924aa",
          "carrier_account_id": "ca_f02596dcabbb46a8ba823280efc277bb"
        },
        {
          "id": "rate_1567998062c445ab909daf872461d15e",
          "object": "Rate",
          "created_at": null,
          "updated_at": null,
          "mode": "test",
          "service": "STANDARD_OVERNIGHT",
          "carrier": "FedEx",
          "rate": "118.00",
          "currency": "USD",
          "retail_rate": null,
          "retail_currency": null,
          "list_rate": null,
          "list_currency": null,
          "delivery_days": 1,
          "delivery_date": "2016-02-18T15:00:00Z",
          "delivery_date_guaranteed": true,
          "est_delivery_days": null,
          "shipment_id": "shp_b701a9da21424a5f85a09530c9f924aa",
          "carrier_account_id": "ca_f02596dcabbb46a8ba823280efc277bb"
        },
        {
          "id": "rate_f9a9706f99754609a60b2ec512e82cbf",
          "object": "Rate",
          "created_at": null,
          "updated_at": null,
          "mode": "test",
          "service": "FEDEX_GROUND",
          "carrier": "FedEx",
          "rate": "17.96",
          "currency": "USD",
          "retail_rate": null,
          "retail_currency": null,
          "list_rate": null,
          "list_currency": null,
          "delivery_days": 4,
          "delivery_date": null,
          "delivery_date_guaranteed": false,
          "est_delivery_days": null,
          "shipment_id": "shp_b701a9da21424a5f85a09530c9f924aa",
          "carrier_account_id": "ca_f02596dcabbb46a8ba823280efc277bb"
        },
      ],
      "refund_status": null,
      "scan_form": null,
      "selected_rate": null,
      "tracker": null,
      "forms": [],
      "fees": [],
      "object": "Shipment"
    },
    {
      "id": "shp_b25c22b64a7f45bd859e826d3701471c",
      "created_at": "2016-02-17T02:51:04Z",
      "updated_at": "2016-02-17T02:51:10Z",
      "is_return": false,
      "messages": [],
      "mode": "test",
      "options": {"currency": "USD", "label_date": null},
      "reference": null,
      "status": "unknown",
      "tracking_code": null,
      "batch_id": null,
      "batch_status": null,
      "batch_message": null,
      "parcel": {
        "id": "prcl_307ea2f3486544e58d5496fc840f6376",
        "object": "Parcel",
        "length": 7.2,
        "width": 1.9,
        "height": 1.0,
        "predefined_package": null,
        "weight": 10.8,
        "created_at": "2013-04-22T05:39:57Z",
        "updated_at": "2013-04-22T05:39:57Z"
      },
      "customs_info": null,
      "to_address": { ... },
      "from_address": { ... },
      "buyer_address": { ... },
      "return_address": { ... },
      "postage_label": null,
      "rates": [],
      "refund_status": null,
      "scan_form": null,
      "selected_rate": null,
      "tracker": null,
      "forms": [],
      "fees": [],
      "object": "Shipment"
    },
  ],
  "rates": [
    {
      "id": "rate_1f168714581b40af965dd740ddf35f69",
      "object": "Rate",
      "created_at": null,
      "updated_at": null,
      "mode": "test",
      "service": "PRIORITY_OVERNIGHT",
      "carrier": "FedEx",
      "rate": "47.36",
      "currency": "USD",
      "retail_rate": null,
      "retail_currency": null,
      "list_rate": null,
      "list_currency": null,
      "delivery_days": 1,
      "delivery_date": "2016-02-18T10:30:00Z",
      "delivery_date_guaranteed": true,
      "est_delivery_days": null,
      "shipment_id": "shp_7a387659db374a8ea197d7bba3009d5d",
      "carrier_account_id": "ca_f02596dcabbb46a8ba823280efc277bb"
    },
    {
      "id": "rate_1567998062c445ab909daf872461d15e",
      "object": "Rate",
      "created_at": null,
      "updated_at": null,
      "mode": "test",
      "service": "STANDARD_OVERNIGHT",
      "carrier": "FedEx",
      "rate": "118.00",
      "currency": "USD",
      "retail_rate": null,
      "retail_currency": null,
      "list_rate": null,
      "list_currency": null,
      "delivery_days": 1,
      "delivery_date": "2016-02-18T15:00:00Z",
      "delivery_date_guaranteed": true,
      "est_delivery_days": null,
      "shipment_id": "shp_7a387659db374a8ea197d7bba3009d5d",
      "carrier_account_id": "ca_f02596dcabbb46a8ba823280efc277bb"
    },
    {
      "id": "rate_f9a9706f99754609a60b2ec512e82cbf",
      "object": "Rate",
      "created_at": null,
      "updated_at": null,
      "mode": "test",
      "service": "FEDEX_GROUND",
      "carrier": "FedEx",
      "rate": "17.96",
      "currency": "USD",
      "retail_rate": null,
      "retail_currency": null,
      "list_rate": null,
      "list_currency": null,
      "delivery_days": 4,
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "est_delivery_days": null,
      "shipment_id": "shp_7a387659db374a8ea197d7bba3009d5d",
      "carrier_account_id": "ca_f02596dcabbb46a8ba823280efc277bb"
    },
  ],
  "object": "Order"
}
GET /orders/:id

Retrieve an Order

An Order can be retrieved by either its id or reference. However it is recommended to use EasyPost's provided identifiers because uniqueness on reference is not enforced.

Retrieve Order Example


curl -X GET https://api.easypost.com/v2/orders/order_... \
  -u <YOUR_TEST/PRODUCTION_API_KEY>:

{
  "id": "order_b39d44e7059a46c8a787174e8320bf1c",
  "mode": "test",
  "reference": null,
  "is_return": false,
  "options": {"currency": "USD","label_date": null},
  "messages": [],
  "created_at": "2016-02-17T02:51:04Z",
  "updated_at": "2016-02-17T02:51:04Z",
  "customs_info": null,
  "to_address": {
    "id": "adr_zMlCRtmt",
    "object": "Address",
    "name": "Dr. Steve Brule",
    "company": null,
    "street1": "179 N Harbor Dr",
    "street2": null,
    "city": "Redondo Beach",
    "state": "CA",
    "zip": "90277",
    "country": "US",
    "phone": "4153334444",
    "mode": "test",
    "carrier_facility": null,
    "residential": null,
    "email": "dr_steve_brule@gmail.com",
    "created_at": "2013-04-22T05:39:56Z",
    "updated_at": "2013-04-22T05:39:56Z"
  },
  "from_address": {
    "id": "adr_VgoLT6Ex",
    "object": "Address",
    "name": "EasyPost",
    "company": null,
    "street1": "417 Montgomery Street",
    "street2": null,
    "city": "San Francisco",
    "state": "CA",
    "zip": "94104",
    "country": "US",
    "phone": "4153334444",
    "email": "support@easypost.com",
    "mode": "test",
    "carrier_facility": null,
    "residential": null,
    "created_at": "2013-04-22T05:39:57Z",
    "updated_at": "2013-04-22T05:39:57Z"
  },
  "buyer_address": {
    "id": "adr_zMlCRtmt",
    "object": "Address",
    "name": "Dr. Steve Brule",
    "company": null,
    "street1": "179 N Harbor Dr",
    "street2": null,
    "city": "Redondo Beach",
    "state": "CA",
    "zip": "90277",
    "country": "US",
    "phone": "4153334444",
    "mode": "test",
    "carrier_facility": null,
    "residential": null,
    "email": "dr_steve_brule@gmail.com",
    "created_at": "2013-04-22T05:39:56Z",
    "updated_at": "2013-04-22T05:39:56Z"
  },
  "return_address": {
    "id": "adr_VgoLT6Ex",
    "object": "Address",
    "name": "EasyPost",
    "company": null,
    "street1": "417 Montgomery Street",
    "street2": null,
    "city": "San Francisco",
    "state": "CA",
    "zip": "94104",
    "country": "US",
    "phone": "4153334444",
    "email": "support@easypost.com",
    "mode": "test",
    "carrier_facility": null,
    "residential": null,
    "created_at": "2013-04-22T05:39:57Z",
    "updated_at": "2013-04-22T05:39:57Z"
  },
  "items": [],
  "containers": [],
  "shipments": [
    {
      "id": "shp_7a387659db374a8ea197d7bba3009d5d",
      "created_at": "2016-02-17T02:51:04Z",
      "updated_at": "2016-02-17T02:51:10Z",
      "is_return": false,
      "messages": [],
      "mode": "test",
      "options": {"currency": "USD", "label_date": null},
      "reference": null,
      "status": "unknown",
      "tracking_code": null,
      "batch_id": null,
      "batch_status": null,
      "batch_message": null,
      "parcel": {
        "id": "prcl_071994637e1046ab98a79f96d8b26488",
        "object": "Parcel",
        "length": 20.2,
        "width": 10.9,
        "height": 5.0,
        "predefined_package": null,
        "weight": 17.5,
        "created_at": "2013-04-22T05:39:57Z",
        "updated_at": "2013-04-22T05:39:57Z"
      },
      "customs_info": null,
      "to_address": {
        "id": "adr_zMlCRtmt",
        "object": "Address",
        "name": "Dr. Steve Brule",
        "company": null,
        "street1": "179 N Harbor Dr",
        "street2": null,
        "city": "Redondo Beach",
        "state": "CA",
        "zip": "90277",
        "country": "US",
        "phone": "4153334444",
        "mode": "test",
        "carrier_facility": null,
        "residential": null,
        "email": "dr_steve_brule@gmail.com",
        "created_at": "2013-04-22T05:39:56Z",
        "updated_at": "2013-04-22T05:39:56Z"
      },
      "from_address": {
        "id": "adr_VgoLT6Ex",
        "object": "Address",
        "name": "EasyPost",
        "company": null,
        "street1": "417 Montgomery Street",
        "street2": null,
        "city": "San Francisco",
        "state": "CA",
        "zip": "94104",
        "country": "US",
        "phone": "4153334444",
        "email": "support@easypost.com",
        "mode": "test",
        "carrier_facility": null,
        "residential": null,
        "created_at": "2013-04-22T05:39:57Z",
        "updated_at": "2013-04-22T05:39:57Z"
      },
      "buyer_address": {
        "id": "adr_zMlCRtmt",
        "object": "Address",
        "name": "Dr. Steve Brule",
        "company": null,
        "street1": "179 N Harbor Dr",
        "street2": null,
        "city": "Redondo Beach",
        "state": "CA",
        "zip": "90277",
        "country": "US",
        "phone": "4153334444",
        "mode": "test",
        "carrier_facility": null,
        "residential": null,
        "email": "dr_steve_brule@gmail.com",
        "created_at": "2013-04-22T05:39:56Z",
        "updated_at": "2013-04-22T05:39:56Z"
      },
      "return_address": {
        "id": "adr_VgoLT6Ex",
        "object": "Address",
        "name": "EasyPost",
        "company": null,
        "street1": "417 Montgomery Street",
        "street2": null,
        "city": "San Francisco",
        "state": "CA",
        "zip": "94104",
        "country": "US",
        "phone": "4153334444",
        "email": "support@easypost.com",
        "mode": "test",
        "carrier_facility": null,
        "residential": null,
        "created_at": "2013-04-22T05:39:57Z",
        "updated_at": "2013-04-22T05:39:57Z"
      },
      "postage_label": null,
      "rates": [
        {
          "id": "rate_1f168714581b40af965dd740ddf35f69",
          "object": "Rate",
          "created_at": null,
          "updated_at": null,
          "mode": "test",
          "service": "PRIORITY_OVERNIGHT",
          "carrier": "FedEx",
          "rate": "47.36",
          "currency": "USD",
          "retail_rate": null,
          "retail_currency": null,
          "list_rate": null,
          "list_currency": null,
          "delivery_days": 1,
          "delivery_date": "2016-02-18T10:30:00Z",
          "delivery_date_guaranteed": true,
          "est_delivery_days": null,
          "shipment_id": "shp_b701a9da21424a5f85a09530c9f924aa",
          "carrier_account_id": "ca_f02596dcabbb46a8ba823280efc277bb"
        },
        {
          "id": "rate_1567998062c445ab909daf872461d15e",
          "object": "Rate",
          "created_at": null,
          "updated_at": null,
          "mode": "test",
          "service": "STANDARD_OVERNIGHT",
          "carrier": "FedEx",
          "rate": "118.00",
          "currency": "USD",
          "retail_rate": null,
          "retail_currency": null,
          "list_rate": null,
          "list_currency": null,
          "delivery_days": 1,
          "delivery_date": "2016-02-18T15:00:00Z",
          "delivery_date_guaranteed": true,
          "est_delivery_days": null,
          "shipment_id": "shp_b701a9da21424a5f85a09530c9f924aa",
          "carrier_account_id": "ca_f02596dcabbb46a8ba823280efc277bb"
        },
        {
          "id": "rate_f9a9706f99754609a60b2ec512e82cbf",
          "object": "Rate",
          "created_at": null,
          "updated_at": null,
          "mode": "test",
          "service": "FEDEX_GROUND",
          "carrier": "FedEx",
          "rate": "17.96",
          "currency": "USD",
          "retail_rate": null,
          "retail_currency": null,
          "list_rate": null,
          "list_currency": null,
          "delivery_days": 4,
          "delivery_date": null,
          "delivery_date_guaranteed": false,
          "est_delivery_days": null,
          "shipment_id": "shp_b701a9da21424a5f85a09530c9f924aa",
          "carrier_account_id": "ca_f02596dcabbb46a8ba823280efc277bb"
        },
      ],
      "refund_status": null,
      "scan_form": null,
      "selected_rate": null,
      "tracker": null,
      "forms": [],
      "fees": [],
      "object": "Shipment"
    },
    {
      "id": "shp_b25c22b64a7f45bd859e826d3701471c",
      "created_at": "2016-02-17T02:51:04Z",
      "updated_at": "2016-02-17T02:51:10Z",
      "is_return": false,
      "messages": [],
      "mode": "test",
      "options": {"currency": "USD", "label_date": null},
      "reference": null,
      "status": "unknown",
      "tracking_code": null,
      "batch_id": null,
      "batch_status": null,
      "batch_message": null,
      "parcel": {
        "id": "prcl_307ea2f3486544e58d5496fc840f6376",
        "object": "Parcel",
        "length": 7.2,
        "width": 1.9,
        "height": 1.0,
        "predefined_package": null,
        "weight": 10.8,
        "created_at": "2013-04-22T05:39:57Z",
        "updated_at": "2013-04-22T05:39:57Z"
      },
      "customs_info": null,
      "to_address": {
        "id": "adr_zMlCRtmt",
        "object": "Address",
        "name": "Dr. Steve Brule",
        "company": null,
        "street1": "179 N Harbor Dr",
        "street2": null,
        "city": "Redondo Beach",
        "state": "CA",
        "zip": "90277",
        "country": "US",
        "phone": "4153334444",
        "mode": "test",
        "carrier_facility": null,
        "residential": null,
        "email": "dr_steve_brule@gmail.com",
        "created_at": "2013-04-22T05:39:56Z",
        "updated_at": "2013-04-22T05:39:56Z"
      },
      "from_address": {
        "id": "adr_VgoLT6Ex",
        "object": "Address",
        "name": "EasyPost",
        "company": null,
        "street1": "417 Montgomery Street",
        "street2": null,
        "city": "San Francisco",
        "state": "CA",
        "zip": "94104",
        "country": "US",
        "phone": "4153334444",
        "email": "support@easypost.com",
        "mode": "test",
        "carrier_facility": null,
        "residential": null,
        "created_at": "2013-04-22T05:39:57Z",
        "updated_at": "2013-04-22T05:39:57Z"
      },
      "buyer_address": {
        "id": "adr_zMlCRtmt",
        "object": "Address",
        "name": "Dr. Steve Brule",
        "company": null,
        "street1": "179 N Harbor Dr",
        "street2": null,
        "city": "Redondo Beach",
        "state": "CA",
        "zip": "90277",
        "country": "US",
        "phone": "4153334444",
        "mode": "test",
        "carrier_facility": null,
        "residential": null,
        "email": "dr_steve_brule@gmail.com",
        "created_at": "2013-04-22T05:39:56Z",
        "updated_at": "2013-04-22T05:39:56Z"
      },
      "return_address": {
        "id": "adr_VgoLT6Ex",
        "object": "Address",
        "name": "EasyPost",
        "company": null,
        "street1": "417 Montgomery Street",
        "street2": null,
        "city": "San Francisco",
        "state": "CA",
        "zip": "94104",
        "country": "US",
        "phone": "4153334444",
        "email": "support@easypost.com",
        "mode": "test",
        "carrier_facility": null,
        "residential": null,
        "created_at": "2013-04-22T05:39:57Z",
        "updated_at": "2013-04-22T05:39:57Z"
      },
      "postage_label": null,
      "rates": [],
      "refund_status": null,
      "scan_form": null,
      "selected_rate": null,
      "tracker": null,
      "forms": [],
      "fees": [],
      "object": "Shipment"
    },
  ],
  "rates": [
    {
      "id": "rate_1f168714581b40af965dd740ddf35f69",
      "object": "Rate",
      "created_at": null,
      "updated_at": null,
      "mode": "test",
      "service": "PRIORITY_OVERNIGHT",
      "carrier": "FedEx",
      "rate": "47.36",
      "currency": "USD",
      "retail_rate": null,
      "retail_currency": null,
      "list_rate": null,
      "list_currency": null,
      "delivery_days": 1,
      "delivery_date": "2016-02-18T10:30:00Z",
      "delivery_date_guaranteed": true,
      "est_delivery_days": null,
      "shipment_id": "shp_7a387659db374a8ea197d7bba3009d5d",
      "carrier_account_id": "ca_f02596dcabbb46a8ba823280efc277bb"
    },
    {
      "id": "rate_1567998062c445ab909daf872461d15e",
      "object": "Rate",
      "created_at": null,
      "updated_at": null,
      "mode": "test",
      "service": "STANDARD_OVERNIGHT",
      "carrier": "FedEx",
      "rate": "118.00",
      "currency": "USD",
      "retail_rate": null,
      "retail_currency": null,
      "list_rate": null,
      "list_currency": null,
      "delivery_days": 1,
      "delivery_date": "2016-02-18T15:00:00Z",
      "delivery_date_guaranteed": true,
      "est_delivery_days": null,
      "shipment_id": "shp_7a387659db374a8ea197d7bba3009d5d",
      "carrier_account_id": "ca_f02596dcabbb46a8ba823280efc277bb"
    },
    {
      "id": "rate_f9a9706f99754609a60b2ec512e82cbf",
      "object": "Rate",
      "created_at": null,
      "updated_at": null,
      "mode": "test",
      "service": "FEDEX_GROUND",
      "carrier": "FedEx",
      "rate": "17.96",
      "currency": "USD",
      "retail_rate": null,
      "retail_currency": null,
      "list_rate": null,
      "list_currency": null,
      "delivery_days": 4,
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "est_delivery_days": null,
      "shipment_id": "shp_7a387659db374a8ea197d7bba3009d5d",
      "carrier_account_id": "ca_f02596dcabbb46a8ba823280efc277bb"
    },
  ],
  "object": "Order"
}
POST /orders/:id/buy

Buy an Order

To purchase an Order you only need to specify the carrier and service to purchase. This operation populates the tracking_code and postage_label attributes of each Shipment.

Buy Order Request Parameters
param example
carrier "FedEx"
service "FEDEX_GROUND"

Buy Order Example


curl -X POST https://api.easypost.com/v2/orders/order_.../buy \
  -u <YOUR_TEST/PRODUCTION_API_KEY>: \
  -d "carrier=FedEx" \
  -d "service=FEDEX_GROUND"

{
  "id": "order_b39d44e7059a46c8a787174e8320bf1c",
  "mode": "test",
  "reference": null,
  "is_return": false,
  "options": {"currency": "USD","label_date": null},
  "messages": [],
  "created_at": "2016-02-17T02:51:04Z",
  "updated_at": "2016-02-17T02:51:04Z",
  "customs_info": null,
  "to_address": { ... },
  "from_address": { ... },
  "buyer_address": { ... },
  "return_address": { ... },
  "items": [],
  "containers": [],
  "shipments": [
    {
      "id": "shp_7a387659db374a8ea197d7bba3009d5d",
      "created_at": "2016-02-17T02:51:04Z",
      "updated_at": "2016-02-17T02:51:10Z",
      "is_return": false,
      "messages": [],
      "mode": "test",
      "options": {"currency": "USD", "label_date": null},
      "reference": null,
      "status": "unknown",
      "tracking_code": null,
      "batch_id": null,
      "batch_status": null,
      "batch_message": null,
      "parcel": {
        "id": "prcl_071994637e1046ab98a79f96d8b26488",
        "object": "Parcel",
        "length": 20.2,
        "width": 10.9,
        "height": 5.0,
        "predefined_package": null,
        "weight": 17.5,
        "created_at": "2013-04-22T05:39:57Z",
        "updated_at": "2013-04-22T05:39:57Z"
      },
      "customs_info": null,
      "to_address": { ... },
      "from_address": { ... },
      "buyer_address": { ... },
      "return_address": { ... },
      "postage_label": {
        "id": "pl_317098e591fc4d0bbc94bf5e7e47668f",
        "object": "PostageLabel",
        "created_at": "2016-02-17T03:10:30Z",
        "updated_at": "2016-02-17T03:10:30Z",
        "date_advance": 0,
        "integrated_form": "none",
        "label_date": "2016-02-17T03:00:16Z",
        "label_resolution": 200,
        "label_size": "PAPER_4X6",
        "label_type": "default",
        "label_url": "http://assets.geteasypost.com/postage_labels/labels/20160217/5205d36225364da686e2ba8476b565a9.png",
        "label_file_type": "image/png",
        "label_pdf_url": null,
        "label_epl2_url": null,
        "label_zpl_url": null
      },
      "rates": [
        {
          "id": "rate_1f168714581b40af965dd740ddf35f69",
          "object": "Rate",
          "created_at": null,
          "updated_at": null,
          "mode": "test",
          "service": "PRIORITY_OVERNIGHT",
          "carrier": "FedEx",
          "rate": "47.36",
          "currency": "USD",
          "retail_rate": null,
          "retail_currency": null,
          "list_rate": null,
          "list_currency": null,
          "delivery_days": 1,
          "delivery_date": "2016-02-18T10:30:00Z",
          "delivery_date_guaranteed": true,
          "est_delivery_days": null,
          "shipment_id": "shp_b701a9da21424a5f85a09530c9f924aa",
          "carrier_account_id": "ca_f02596dcabbb46a8ba823280efc277bb"
        },
        {
          "id": "rate_1567998062c445ab909daf872461d15e",
          "object": "Rate",
          "created_at": null,
          "updated_at": null,
          "mode": "test",
          "service": "STANDARD_OVERNIGHT",
          "carrier": "FedEx",
          "rate": "118.00",
          "currency": "USD",
          "retail_rate": null,
          "retail_currency": null,
          "list_rate": null,
          "list_currency": null,
          "delivery_days": 1,
          "delivery_date": "2016-02-18T15:00:00Z",
          "delivery_date_guaranteed": true,
          "est_delivery_days": null,
          "shipment_id": "shp_b701a9da21424a5f85a09530c9f924aa",
          "carrier_account_id": "ca_f02596dcabbb46a8ba823280efc277bb"
        },
        {
          "id": "rate_f9a9706f99754609a60b2ec512e82cbf",
          "object": "Rate",
          "created_at": null,
          "updated_at": null,
          "mode": "test",
          "service": "FEDEX_GROUND",
          "carrier": "FedEx",
          "rate": "17.96",
          "currency": "USD",
          "retail_rate": null,
          "retail_currency": null,
          "list_rate": null,
          "list_currency": null,
          "delivery_days": 4,
          "delivery_date": null,
          "delivery_date_guaranteed": false,
          "est_delivery_days": null,
          "shipment_id": "shp_b701a9da21424a5f85a09530c9f924aa",
          "carrier_account_id": "ca_f02596dcabbb46a8ba823280efc277bb"
        },
      ],
      "refund_status": null,
      "scan_form": null,
      "selected_rate": null,
      "tracker": null,
      "forms": [],
      "fees": [],
      "object": "Shipment"
    },
    {
      "id": "shp_b25c22b64a7f45bd859e826d3701471c",
      "created_at": "2016-02-17T02:51:04Z",
      "updated_at": "2016-02-17T02:51:10Z",
      "is_return": false,
      "messages": [],
      "mode": "test",
      "options": {"currency": "USD", "label_date": null},
      "reference": null,
      "status": "unknown",
      "tracking_code": null,
      "batch_id": null,
      "batch_status": null,
      "batch_message": null,
      "parcel": {
        "id": "prcl_307ea2f3486544e58d5496fc840f6376",
        "object": "Parcel",
        "length": 7.2,
        "width": 1.9,
        "height": 1.0,
        "predefined_package": null,
        "weight": 10.8,
        "created_at": "2013-04-22T05:39:57Z",
        "updated_at": "2013-04-22T05:39:57Z"
      },
      "customs_info": null,
      "to_address": { ... },
      "from_address": { ... },
      "buyer_address": { ... },
      "return_address": { ... },
      "postage_label": {
        "id": "pl_1a118b22c63f4bf9825437c01f6f9f38",
        "object": "PostageLabel",
        "created_at": "2016-02-17T03:10:32Z",
        "updated_at": "2016-02-17T03:10:32Z",
        "date_advance": 0,
        "integrated_form": "none",
        "label_date": "2016-02-17T03:00:16Z",
        "label_resolution": 200,
        "label_size": "PAPER_4X6",
        "label_type": "default",
        "label_url": "http://assets.geteasypost.com/postage_labels/labels/20160217/788f130b67f34a92b65b8b6f5c17e792.png",
        "label_file_type": "image/png",
        "label_pdf_url": null,
        "label_epl2_url": null,
        "label_zpl_url": null
      },
      "rates": [],
      "refund_status": null,
      "scan_form": null,
      "selected_rate": null,
      "tracker": null,
      "forms": [],
      "fees": [],
      "object": "Shipment"
    },
  ],
  "rates": [
    {
      "id": "rate_1f168714581b40af965dd740ddf35f69",
      "object": "Rate",
      "created_at": null,
      "updated_at": null,
      "mode": "test",
      "service": "PRIORITY_OVERNIGHT",
      "carrier": "FedEx",
      "rate": "47.36",
      "currency": "USD",
      "retail_rate": null,
      "retail_currency": null,
      "list_rate": null,
      "list_currency": null,
      "delivery_days": 1,
      "delivery_date": "2016-02-18T10:30:00Z",
      "delivery_date_guaranteed": true,
      "est_delivery_days": null,
      "shipment_id": "shp_7a387659db374a8ea197d7bba3009d5d",
      "carrier_account_id": "ca_f02596dcabbb46a8ba823280efc277bb"
    },
    {
      "id": "rate_1567998062c445ab909daf872461d15e",
      "object": "Rate",
      "created_at": null,
      "updated_at": null,
      "mode": "test",
      "service": "STANDARD_OVERNIGHT",
      "carrier": "FedEx",
      "rate": "118.00",
      "currency": "USD",
      "retail_rate": null,
      "retail_currency": null,
      "list_rate": null,
      "list_currency": null,
      "delivery_days": 1,
      "delivery_date": "2016-02-18T15:00:00Z",
      "delivery_date_guaranteed": true,
      "est_delivery_days": null,
      "shipment_id": "shp_7a387659db374a8ea197d7bba3009d5d",
      "carrier_account_id": "ca_f02596dcabbb46a8ba823280efc277bb"
    },
    {
      "id": "rate_f9a9706f99754609a60b2ec512e82cbf",
      "object": "Rate",
      "created_at": null,
      "updated_at": null,
      "mode": "test",
      "service": "FEDEX_GROUND",
      "carrier": "FedEx",
      "rate": "17.96",
      "currency": "USD",
      "retail_rate": null,
      "retail_currency": null,
      "list_rate": null,
      "list_currency": null,
      "delivery_days": 4,
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "est_delivery_days": null,
      "shipment_id": "shp_7a387659db374a8ea197d7bba3009d5d",
      "carrier_account_id": "ca_f02596dcabbb46a8ba823280efc277bb"
    },
  ],
  "object": "Order"
}

Pickups

The Pickup object allows you to schedule a pickup from your carrier from your customer's residence or place of business. Supported carriers include USPS, UPS, FedEx, and DHL Express.

After a Pickup is successfully created, it will automatically fetch PickupRates for each CarrierAccount specified that supports scheduled pickups. Then a PickupRate must be selected and purchased before the pickup can be successfully scheduled.

Pickup Object

attribute type specification
id string unique, begins with "pickup_"
object string "Pickup"
reference string An optional field that may be used in place of ID in some API endpoints
mode string "test" or "production"
status string One of: "unknown", "scheduled", "missed", "canceled", or "completed"
min_datetime datetime The earliest time at which the package is available to pick up
max_datetime datetime The latest time at which the package is available to pick up. Must be later than the min_datetime
is_account_address boolean Is the pickup address the account's address?
instructions string Additional text to help the driver successfully obtain the package
messages Message array A list of messages containing carrier errors encountered during pickup rate generation
confirmation string The confirmation number for a booked pickup from the carrier
shipment Shipment The associated Shipment
address Address The associated Address
carrier_accounts CarrierAccount array The list of carriers (if empty, all carriers were used) used to generate pickup rates
pickup_rates PickupRate array The list of different pickup rates across valid carrier accounts for the shipment
created_at datetime
updated_at datetime

PickupRate Object

attribute type specification
id string unique, begins with 'pickuprate_'
object string "PickupRate"
mode string "test" or "production"
service string service name
carrier string name of carrier
rate string the actual rate quote for this service
currency string currency for the rate
pickup_id string the ID of the pickup this is a quote for
created_at datetime
updated_at datetime
POST /pickups

Create a Pickup

Creating a Pickup will automatically fetch rates for the given time frame and location.

Pickups work with existing shipments and either a fully-specified Address object or id. The examples below assume that a shipment and address have both already been created.

Create Pickup Request Parameters
param example
address <Address>
shipment <Shipment>
carrier_accounts [<CarrierAccount>,<CarrierAccount>,...]
instructions "Knock loudly"
reference "my-custom-pickup"
is_account_address true
min_datetime 2014-10-21 10:30:00
max_datetime 2014-10-22 10:30:00

Create Pickup Example


curl -X POST https://api.easypost.com/v2/pickups \
  -u <YOUR_TEST/PRODUCTION_API_KEY>: \
  -d 'pickup[reference]=my-first-pickup' \
  -d 'pickup[min_datetime]=2014-10-20 17:10:00' \
  -d 'pickup[max_datetime]=2014-10-21 10:30:00' \
  -d 'pickup[shipment][id]=shp_...' \
  -d 'pickup[address][id]=adr_...' \
  -d 'pickup[is_account_address]=false' \
  -d 'pickup[instructions]=Special pickup instructions'

{
  "id": "pickup_ebae2c59mdk83jsh39ma3a056ab3d1f1",
  "object": "Pickup",
  "created_at": "2015-03-17T20:03:07Z",
  "updated_at": "2015-03-17T20:03:07Z",
  "mode": "test",
  "status": "unknown",
  "reference": "my-first-pickup",
  "min_datetime": "2015-03-18T08:00:00Z",
  "max_datetime": "2015-03-18T18:00:00Z",
  "is_account_address": false,
  "instructions": "My special instructions",
  "messages": [],
  "confirmation": null,
  "address": {
    "id": "adr_72N1gd6k",
    "object": "Address",
    "created_at": "2015-03-17T20:03:06Z",
    "updated_at": "2015-03-17T20:03:06Z",
    "name": "John Smith",
    "company": "",
    "street1": "123 Main St",
    "street2": "",
    "city": "Park City",
    "state": "UT",
    "zip": "84060",
    "country": "US",
    "phone": "5551231234",
    "email": null,
    "mode": "test",
    "carrier_facility": null,
    "residential": null,
    "federal_tax_id": null,
    "state_tax_id": null
  },
  "carrier_accounts": [],
  "pickup_rates": [
    {
      "created_at": "2015-03-17T20:03:07Z",
      "currency": "USD",
      "mode": "test",
      "rate": "5.96",
      "service": "Future-day Pickup",
      "updated_at": "2015-03-17T20:03:07Z",
      "carrier": "UPS",
      "pickup_id": "pickup_ebae2c59mdk83jsh39ma3a056ab3d1f1",
      "id": "pickuprate_092af6ac0opkhsfg72hj23eab18964bf2",
      "object": "PickupRate"
    }
  ]
}
GET /pickups/:id

Retrieve a Pickup

A Pickup object can be retrieved by either an id or reference. However it is recommended to use EasyPost's provided identifiers because uniqueness on reference is not enforced.

Retrieve Pickup Example


curl -X GET https://api.easypost.com/v2/pickups/pck_... \
  -u <YOUR_TEST/PRODUCTION_API_KEY>:

{
  "id": "pickup_ebae2c59mdk83jsh39ma3a056ab3d1f1",
  "object": "Pickup",
  "created_at": "2015-03-17T20:03:07Z",
  "updated_at": "2015-03-17T20:03:07Z",
  "mode": "test",
  "status": "unknown",
  "reference": "my-first-pickup",
  "min_datetime": "2015-03-18T08:00:00Z",
  "max_datetime": "2015-03-18T18:00:00Z",
  "is_account_address": false,
  "instructions": "My special instructions",
  "messages": [],
  "confirmation": null,
  "address": {
    "id": "adr_72N1gd6k",
    "object": "Address",
    "created_at": "2015-03-17T20:03:06Z",
    "updated_at": "2015-03-17T20:03:06Z",
    "name": "John Smith",
    "company": "",
    "street1": "123 Main St",
    "street2": "",
    "city": "Park City",
    "state": "UT",
    "zip": "84060",
    "country": "US",
    "phone": "5551231234",
    "email": null,
    "mode": "test",
    "carrier_facility": null,
    "residential": null,
    "federal_tax_id": null,
    "state_tax_id": null
  },
  "carrier_accounts": [],
  "pickup_rates": [
    {
      "created_at": "2015-03-17T20:03:07Z",
      "currency": "USD",
      "mode": "test",
      "rate": "5.96",
      "service": "Future-day Pickup",
      "updated_at": "2015-03-17T20:03:07Z",
      "carrier": "UPS",
      "pickup_id": "pickup_ebae2c59mdk83jsh39ma3a056ab3d1f1",
      "id": "pickuprate_092af6ac0opkhsfg72hj23eab18964bf2",
      "object": "PickupRate"
    }
  ]
}
POST /pickups/:id/buy

Buy a Pickup

To purchase a Pickup a PickupRate must be specified by its carrier and service name, instead of its id. The client libraries will handle this automatically if a PickupRate is provided.

POST /pickups/:id/buy

Buy Pickup Request Parameters
param example
carrier "UPS"
service "Same-day Pickup"

Buy Pickup Example


curl -X POST https://api.easypost.com/v2/pickups/pck_.../buy \
  -u <YOUR_TEST/PRODUCTION_API_KEY>: \
  -d 'carrier=UPS' \
  -d 'service=Same-Day Pickup'

{
  "id": "pickup_ebae2c59mdk83jsh39ma3a056ab3d1f1",
  "object": "Pickup",
  "created_at": "2015-03-17T20:03:07Z",
  "updated_at": "2015-03-17T20:03:07Z",
  "mode": "test",
  "status": "scheduled",
  "reference": "my-first-pickup",
  "min_datetime": "2015-03-18T08:00:00Z",
  "max_datetime": "2015-03-18T18:00:00Z",
  "is_account_address": false,
  "instructions": "My special instructions",
  "messages": [],
  "confirmation": "C377283498",
  "address": {
    "id": "adr_72N1gd6k",
    "object": "Address",
    "created_at": "2015-03-17T20:03:06Z",
    "updated_at": "2015-03-17T20:03:06Z",
    "name": "John Smith",
    "company": "",
    "street1": "123 Main St",
    "street2": "",
    "city": "Park City",
    "state": "UT",
    "zip": "84060",
    "country": "US",
    "phone": "5551231234",
    "email": null,
    "mode": "test",
    "carrier_facility": null,
    "residential": null,
    "federal_tax_id": null,
    "state_tax_id": null
  },
  "carrier_accounts": [],
  "pickup_rates": [
    {
      "created_at": "2015-03-17T20:03:07Z",
      "currency": "USD",
      "mode": "test",
      "rate": "5.96",
      "service": "Future-day Pickup",
      "updated_at": "2015-03-17T20:03:07Z",
      "carrier": "UPS",
      "pickup_id": "pickup_ebae2c59mdk83jsh39ma3a056ab3d1f1",
      "id": "pickuprate_092af6ac0opkhsfg72hj23eab18964bf2",
      "object": "PickupRate"
    }
  ]
}
POST /pickups/:id/cancel

Cancel an Pickup

You may cancel a Pickup anytime before it has been completed. It requires no additional parameters other than the id or reference. The status will change to "canceled" on success.

Cancel Pickup Example


curl -X POST https://api.easypost.com/v2/pickups/pck_.../cancel \
  -u <YOUR_TEST/PRODUCTION_API_KEY>:

{
  "id": "pickup_ebae2c59mdk83jsh39ma3a056ab3d1f1",
  "object": "Pickup",
  "created_at": "2015-03-17T20:03:07Z",
  "updated_at": "2015-03-17T20:03:07Z",
  "mode": "test",
  "status": "canceled",
  "reference": "my-first-pickup",
  "min_datetime": "2015-03-18T08:00:00Z",
  "max_datetime": "2015-03-18T18:00:00Z",
  "is_account_address": false,
  "instructions": "My special instructions",
  "messages": [],
  "confirmation": "C377283498",
  "address": {
    "id": "adr_72N1gd6k",
    "object": "Address",
    "created_at": "2015-03-17T20:03:06Z",
    "updated_at": "2015-03-17T20:03:06Z",
    "name": "John Smith",
    "company": "",
    "street1": "123 Main St",
    "street2": "",
    "city": "Park City",
    "state": "UT",
    "zip": "84060",
    "country": "US",
    "phone": "5551231234",
    "email": null,
    "mode": "test",
    "carrier_facility": null,
    "residential": null,
    "federal_tax_id": null,
    "state_tax_id": null
  },
  "carrier_accounts": [],
  "pickup_rates": [
    {
      "created_at": "2015-03-17T20:03:07Z",
      "currency": "USD",
      "mode": "test",
      "rate": "5.96",
      "service": "Future-day Pickup",
      "updated_at": "2015-03-17T20:03:07Z",
      "carrier": "UPS",
      "pickup_id": "pickup_ebae2c59mdk83jsh39ma3a056ab3d1f1",
      "id": "pickuprate_092af6ac0opkhsfg72hj23eab18964bf2",
      "object": "PickupRate"
    }
  ]
}

API Keys

When performing opterations on API Keys for a specific user, you must be authencicated using a production key.

API Keys full response structure

attribute type specification
id string The User id of the authenticated User making the API Key request
children array of API Key response structures A list of all Child Users presented with ONLY id, children, and key array structures.
keys API Key array The list of all API keys active for an account, both for "test" and "production" modes.

API Key object

attribute type specification
object string "ApiKey"
mode string "test" or "production"
key string The actual key value to use for authentication
created_at datetime
GET /api_keys
Production Only This call will only work with your production API Key.

Retrieve API Keys

Both production and test keys will be returned a User and all of its children. If the request is authenticated as a Child only the API Keys for that Child will be returned.

Retrieve API Keys Example


curl -X GET https://api.easypost.com/v2/api_keys \
  -u <YOUR_PRODUCTION_API_KEY>:

{
  "id": "user_...",
  "keys": [
    {
      "object": "ApiKey",
      "key": "342sCQQQQQEKypxIg",
      "mode": "test",
      "created_at": "2014-04-09T01:00:01Z"
    }, {
      "object": "ApiKey",
      "key": "dsa3OdoUG1q2fa7D5FBg",
      "mode": "production",
      "created_at": "2014-04-09T01:00:02Z"
    }
  ],
  "children": [
    {
      "id": "user_...",
      "keys": [
        {
          "object": "ApiKey",
          "key": "d32fdddfdfsdf3AA",
          "mode": "test",
          "created_at": "2015-02-11T01:01:01Z"
        }, {
          "object": "ApiKey",
          "key": "34363fg11g545345fs",
          "mode": "production",
          "created_at": "2015-02-11T01:01:01Z"
        }
      ],
      "children": []
    }
  ]
}

Users

The User object can be used to manage your own account and to create child accounts. Only a Production mode API key can be used to make requests against the Users API.

Balance and recharge values on User objects are expressed in higher precision USD.

User Object

attribute type specification
id string Unique, begins with "user_"
object string "User"
parent_id string The ID of the parent user object. Top-level users are defined as users with no parent
name string First and last name required
email string Required
phone_number string Optional
balance string Formatted as string "XX.XXXXX"
recharge_amount string USD formatted dollars and cents, delimited by a decimal point
secondary_recharge_amount string USD formatted dollars and cents, delimited by a decimal point
recharge_threshold string Number of cents USD that when your balance drops below, we automatically recharge your account with your primary payment method.
children User array array All associated children
POST /users
Production Only This call will only work with your production API Key.

Create a User

There are two kinds of accounts. The first is the standard (parent) User object. It represents your account state, settings, and credentials to log in via the website.

The second is the child User, which is a User that belongs to a parent. The following example demonstrates creating a parent user; child users are discussed in more depth in their own section.

Creating a non-child user requires specifically NOT using an API key when making the request. Any User creation attempts made by an authenticated request will be interpreted as the creation of a child.

Create User Request Parameters
param example
name Chad Vader
password 4thedarkside
password_confirmation 4thedarkside
email c.vader@example.com
phone_number 555-123-4321

Create User Example


# Note that there is no API key submitted with this request,
# as it must be made unauthenticated to register a new account
# instead of a child user.

curl -X POST https://api.easypost.com/v2/users \
  -d 'user[name]=Chad Vader' \
  -d 'user[email]=c.vader@example.com' \
  -d 'user[password]=4theempire' \
  -d 'user[password_confirmation]=4theempire' \
  -d 'user[phone_number]=555-123-4321'

{
  "id": "user_qqUy4rWef",
  "object": "User",
  "parent_id": null,
  "name": "Chad Vader",
  "email": "c.vader@example.com",
  "phone_number": "555-123-4321",
  "balance": "0.00000",
  "price_per_shipment": 5,
  "recharge_amount": "100.00",
  "secondary_recharge_amount": "100.00",
  "recharge_threshold": 0,
  "children": []
}
GET /users/:id
Production Only This call will only work with your production API Key.

Retrieve a User

Each User can be retrieved individually by id. Any id provided must be either the id of the authenticated User or the id of one of its children. Additionally, to retrieve the authenticated User directly no id is required.

Retrieve User Example


# Option 1: Accessing the user of the given API key
curl -X GET https://api.easypost.com/v2/users \
  -u <YOUR_PRODUCTION_API_KEY>:

# Option 2: Passing an ID
curl -X GET https://api.easypost.com/v2/users/user_... \
  -u <YOUR_PRODUCTION_API_KEY>:

{
  "id": "user_qqUy4rWef",
  "object": "User",
  "parent_id": null,
  "name": "Chad Vader",
  "email": "c.vader@example.com",
  "phone_number": "555-123-4321",
  "balance": "1234.99000",
  "price_per_shipment": 5,
  "recharge_amount": "5000.00",
  "secondary_recharge_amount": "250.00",
  "recharge_threshold": "100.00",
  "children": []
}
PUT /users/:id
Production Only This call will only work with your production API Key.

Update a User

Just like retrieving a User they can be updated using the same patterns. Passing an id will allow the update of a child or the authenticated User. Passing no id will update the authenticated User.

Since children also have the ability to authenticate themselves they can be updated without passing an id. Children may only have their "name" field updated, all other fields are ignored.

All update requests are considered partial updates. Only attributes specifically passed in will be updated. The current_password attribute is required when updaing email or password.

Update User Request Parameters
param example
email "foo@example.com"
password "hunter2"
password_confirmation "hunter2"
current_password "Cthon98"
name "Azure Diamond"
phone_number "555-867-5309"
recharge_amount "100.00"
secondary_recharge_amount "50.00"
recharge_threshold "20.00"

Update User Example


# Option 1: Updating the user of the given API key
curl -X PUT https://api.easypost.com/v2/users \
  -u <YOUR_PRODUCTION_API_KEY>: \
  -d 'user[recharge_threshold]=50.00'

# Option 2: Updating by ID
curl -X PUT https://api.easypost.com/v2/users/user_... \
  -u <YOUR_PRODUCTION_API_KEY>: \
  -d 'user[name]=Test Child'

{
  "id": "user_qqUy4rWef",
  "object": "User",
  "parent_id": null,
  "name": "Update Me",
  "email": "c.vader@example.com",
  "phone_number": "555-123-4321",
  "balance": "1234.99000",
  "price_per_shipment": 5,
  "recharge_amount": "50.00",
  "secondary_recharge_amount": "250.00",
  "recharge_threshold": "100.00",
  "children": []
}

Child Users

A child User can be created for the purpose of organizing larger integrations with EasyPost. If you are representing multiple end users, each with their own set of carrier credentials it can make sense to organize them a child User.

Other than organizing activity and CarrierAccounts the central advantage of a child account is that billing flows through the parent's payment information. This allows the child to not have to duplicate payment information.

The structure of a child User is identicial to its parent, which means that their representations contain many more properties than are actually used. As well, creating a child User requires almost none of the properties necessary for creating a top-level User.

Child User Object

attribute type specification
id string unique, begins with "user_"
object string "User"
parent_id string The id of the parent User. All children have a parent id
name string Automatically generated if none is provided
email string Ignored
phone_number string Ignored
balance string Children use parent's billing, children have a balance of $0.00
recharge_amount Ignored Children use parent's billing, this number is ignored
secondary_recharge_amount Ignored Children use the parent's billing, this number is ignored
recharge_threshold Ignored Children use the parent's billing, this number is ignored
children Ignored Children cannot have further children, so this array is always empty
POST /users
Production Only This call will only work with your production API Key.

Create a Child User

Children use the billing information of the parent, and are not able to log in to the website. Any User creation attempt made with an authenticated request (via API key or cookie) is assumed to be the creation of a child of that User.

The name attribute is the only user-settable value on child accounts. It is also optional, as one will automatically generated if it is not supplied.

Create Child User Request Parameters
param example
name Imma Child

Create Child User Example


curl -X POST https://api.easypost.com/v2/users \
  -u <YOUR_PRODUCTION_API_KEY>: \
  -d 'user[name]=Imma Child'

{
  "id": "user_ttUy4rWef",
  "object": "User",
  "parent_id": "user_qqUy3rQer",
  "name": "Imma Child",
  "email": "child_user_ttUy4rWef@example.com",
  "phone_number": "8005550100",
  "balance": "0.00000",
  "price_per_shipment": 5,
  "recharge_amount": "100.00",
  "secondary_recharge_amount": "100.00",
  "recharge_threshold": "0.00",
  "children": []
}

Carrier Types

The CarrierType object provides an interface for determining the valid fields of a CarrierAccount. The list of CarrierType objects only changes when a new carrier is added to EasyPost.

Only one USPS CarrierAccount can be associated with your EasyPost account. Thus, if you have deleted your USPS account it will show in the CarrierType list.

The CarrierType objects consist of their top level attributes as well as a fields object that contains credentials and sometimes test_credentials sub-objects, which themselves are collections of attributes for CarrierAccount creation as well as metadata about presentation and the naming of said attributes.

There are a couple special case CarrierAccounts, with structures differing somewhat from the norm. For instance, instead of credentials for EndiciaAccount, it has only auto_link: true, which indicates that it is an account that can be added or removed without any carrier-specific fields.

The other custom option in the fields list is custom_workflow: true, which indicates that the EasyPost website interface includes special processing for signups for the associated CarrierType. Carriers with a custom workflow will also present their normal credential rules, but it is considered unsafe to directly add a CarrierAccount of this type with these attributes filled out via another source than the EasyPost custom workflow.

CarrierType object

attribute type specification
object string "CarrierType"
type string Specifies the CarrierAccount type. Note that "EndiciaAccount" is the current USPS integration account type
fields fields object Contains at least one of the following keys: "auto_link", "credentials", "test_credentials", and "custom_workflow"

fields object

attribute type specification
auto_link boolean If this key is present with the value of true, no other attributes are needed for CarrierAccount creation
custom_workflow boolean If this key is present with the value of true, CarrierAccount creation of this type requires extra work not handled by the CarrierAccount standard API
credentials credentials object If this object is present, required attribute names and their metadata are presented inside
test_credentials credentials object If this object is present, it contains attribute names and metadata just as the credentials object. It is not required for CarrierAccount creation if you do not plan on using the carrier account for test mode

attribute objects from credentials/test_credentials

attribute type specification
name string The key for each attribute sub-object within credentials is the name of the attribute for submission on CarrierAccounts
visibility string There are five possible values, which encode the security need and storage type for each attribute: "visible", "checkbox", "fake", "password", and "masked"
label string Most attributes have generic names, so for clarity a "label" value is provided for clearer representation when rendering forms
GET /carrier_types
Production Only This call will only work with your production API Key.

Retrieve available Carrier Types

The CarrierType list is an unpaginated list of all carrier types available to the account of the given API key.

Retrieve available Carrier Type Example


curl -X GET https://api.easypost.com/v2/carrier_types \
  -u <YOUR_PRODUCTION_API_KEY>:

[
  {
    "object": "CarrierType",
    "type": "EndiciaAccount",
    "readable": "USPS",
    "logo": null,
    "fields": {
      "auto_link": true
    }
  },
  {
    "object": "CarrierType",
    "type": "AramexAccount",
    "readable": "Aramex",
    "logo": null,
    "fields": {
      "credentials": {
        "username": {
          "visibility": "visible",
          "label": "ARAMEX Username"
        },
        "password": {
          "visibility": "password",
          "label": "ARAMEX Password"
        },
        "account_number": {
          "visibility": "visible",
          "label": "ARAMEX Account Number"
        },
        "account_entity": {
          "visibility": "visible",
          "label": "ARAMEX Account Entity"
        },
        "account_pin": {
          "visibility": "visible",
          "label": "ARAMEX Account Pin"
        },
        "account_country": {
          "visibility": "visible",
          "label": "ARAMEX Account Country"
        }
      }
    }
  },
  {
    "object": "CarrierType",
    "type": "CanadaPostAccount",
    "readable": "Canada Post",
    "logo": null,
    "fields": {
      "credentials": {
        "api_key": {
          "visibility": "masked",
          "label": "CanadaPost API Key"
        },
        "contract_id": {
          "visibility": "visible",
          "label": "CanadaPost Contract ID"
        },
        "customer_number": {
          "visibility": "visible",
          "label": "CanadaPost Customer Number"
        },
        "has_credit_card": {
          "visibility": "checkbox",
          "label": "CanadaPost account has credit card?"
        }
      },
      "custom_workflow": true
    }
  }
]

Carrier Accounts

A CarrierAccount encapsulates your credentials with the carrier. The CarrierAccount object provides CRUD operations for all CarrierAccounts.

Each EasyPost account is automatically provided a USPS account managed by EasyPost.

Other operations, such as Shipment creation, can reference CarrierAccounts to reduce the scope of data returned. For instance, you may have multiple warehouses that need to use distinct FedEx SmartPost credentials to request the correct rates. Rate objects will include a carrier_account_id field which can be used to determine the account used for rating.

CarrierAccount object

attribute type specification
id string Unique, begins with "ca_"
object string "CarrierAccount"
type string The name of the carrier type. Note that "EndiciaAccount" is the current USPS integration account type
fields Fields object Contains "credentials" and/or "test_credentials", or may be empty
clone boolean If clone is true, only the reference and description are possible to update
description string An optional, user-readable field to help distinguish accounts
reference string An optional field that may be used in place of carrier_account_id in other API endpoints
readable string The name used when displaying a readable value for the type of the account
credentials object Unlike the "credentials" object contained in "fields", this nullable object contains just raw credential pairs for client library consumption
test_credentials object Unlike the "test_credentials" object contained in "fields", this nullable object contains just raw test_credential pairs for client library consumption
created_at datetime
updated_at datetime

Fields object

attribute type specification
credentials Field object Credentials used in the production environment.
test_credentials Field object Credentials used in the test environment.
auto_link boolean For USPS this designates that no credentials are required.
custom_workflow boolean When present, a seperate authentication process will be required through the UI to link this account type.

Field object

attribute type specification
key string Each key in the sub-objects of a CarrierAccount's fields is the name of a settable field
visibility string The visibility value is used to control form field types, and is discussed in the CarrierType section
label string The label value is used in form rendering to display a more precise field name
value string Checkbox fields use "0" and "1" as False and True, all other field types present plaintext, partly-masked, or masked credential data for reference
POST /carrier_accounts
Production Only This call will only work with your production API Key.

Create a Carrier Account

CarrierAccount objects may be managed through the EasyPost API using the Production mode API key only. Multiple accounts can be added for a single carrier (with the exception of the USPS).

The CarrierType of the prefered CarrierAccount should be consulted before attempting to create a new CarrierAccount, as it will inform you of the field names expected by a certain carrier.

Create Carrier Account Example


curl -X POST https://api.easypost.com/v2/carrier_accounts \
  -u <YOUR_PRODUCTION_API_KEY>: \
  -d 'carrier_account[type]=UpsAccount' \
  -d 'carrier_account[description]=NY Location UPS Account' \
  -d 'carrier_account[reference]=my-reference' \
  -d 'carrier_account[credentials][account_number]=A1A1A1' \
  -d 'carrier_account[credentials][user_id]=USERID' \
  -d 'carrier_account[credentials][password]=PASSWORD' \
  -d 'carrier_account[credentials][access_license_number]=ALN'

{
  "id": "ca_27839172aee03918a701",
  "object": "CarrierAccount",
  "type": "UpsAccount",
  "description": "NY Location UPS Account",
  "clone": false,
  "created_at": "2016-01-13T01:00:01Z",
  "updated_at": "2016-01-13T01:00:01Z",
  "reference": "my-reference",
  "readable": "UPS",
  "logo": null,
  "fields": {
    "credentials": {
      "account_number": {
        "visibility": "visible",
        "label": "UPS Account Number",
        "value": "A1A1A1"
      },
      "access_license_number": {
        "visibility": "visible",
        "label": "UPS Access License Number",
        "value": "ALN"
      },
      "user_id": {
        "visibility": "visible",
        "label": "UPS.com User ID",
        "value": "USERID"
      },
      "password": {
        "visibility": "password",
        "label": "UPS.com Password",
        "value": "********"
      }
    }
  },
  "credentials": {
    "account_number": "A1A1A1",
    "user_id": "USERID",
    "password": "********",
    "access_license_number": "ALN"
  },
  "test_credentials": null
}
GET /carrier_accounts
Production Only This call will only work with your production API Key.

List all Carrier Accounts

Retrieve an unpaginated list of all CarrierAccounts available to the authenticated account. Only Production API keys may be used to retrieve this list, as there is no test mode equivalent.

List Carrier Account Example


curl -X GET https://api.easypost.com/v2/carrier_accounts \
  -u <YOUR_PRODUCTION_API_KEY>:

[
  {
    "id": "ca_34534634765aa3123",
    "object": "CarrierAccount",
    "type": "EndiciaAccount",
    "clone": true,
    "created_at": "2016-01-13T01:00:00Z",
    "updated_at": "2016-01-13T01:00:00Z",
    "description": "USPS Account",
    "reference": null,
    "readable": "USPS",
    "logo": null,
    "fields": {},
    "credentials": null,
    "test_credentials": null
  },
  {
    "id": "ca_27839172aee03918a701",
    "object": "CarrierAccount",
    "type": "AsendiaAccount",
    "clone": false,
    "created_at": "2016-01-13T01:00:01Z",
    "updated_at": "2016-01-13T01:00:01Z",
    "description": "Roswell",
    "reference": "my_custom_carrier",
    "readable": "Asendia USA",
    "logo": "/img/carriers/asendia-logo-ca.png",
    "fields": {
      "credentials": {
        "account_number": {
          "visibility": "visible",
          "label": "Asendia Account Number",
          "value": "12345"
        },
        "company_name": {
          "visibility": "visible",
          "label": "Company Name",
          "value": "CarryMe"
        },
        "ftp_username": {
          "visibility": "visible",
          "label": "FTP Username",
          "value": "foouser"
        },
        "ftp_password": {
          "visibility": "password",
          "label": "FTP Password",
          "value": "********"
        },
        "prioritytracked": {
          "visibility": "checkbox",
          "label": "Priority Tracked",
          "value": "1"
        },
        "pmi": {
          "visibility": "checkbox",
          "label": "PMI",
          "value": "0"
        },
        "epacket": {
          "visibility": "checkbox",
          "label": "ePacket",
          "value": "1"
        },
        "ipa": {
          "visibility": "checkbox",
          "label": "IPA",
          "value": "0"
        },
        "isal": {
          "visibility": "checkbox",
          "label": "ISAL",
          "value": "0"
        }
      }
    },
    "credentials": {
      "account_number": "12345",
      "company_name": "CarryMe",
      "ftp_username": "foouser",
      "ftp_password": "********",
      "prioritytracked": "1",
      "pmi": "0",
      "epacket": "1",
      "ipa": "0",
      "isal": "0"
    },
    "test_credentials": null
  }
]
GET /carrier_accounts/:id
Production Only This call will only work with your production API Key.

Retrieve a Carrier Account

Retrieve a CarrierAccount by either its id or reference. However it is recommended to use EasyPost's provided identifiers because we do not enforce a unique reference.

Retrieve Carrier Account Example


curl -X GET https://api.easypost.com/v2/carrier_accounts/ca_... \
  -u <YOUR_PRODUCTION_API_KEY>:

{
  "id": "ca_27839172aee03918a701",
  "object": "CarrierAccount",
  "type": "AsendiaAccount",
  "clone": false,
  "created_at": "2016-01-13T01:00:01Z",
  "updated_at": "2016-01-13T01:00:01Z",
  "description": "Roswell",
  "reference": "my_custom_carrier",
  "readable": "Asendia USA",
  "logo": null,
  "fields": {
    "credentials": {
      "account_number": {
        "visibility": "visible",
        "label": "Asendia Account Number",
        "value": "12345"
      },
      "company_name": {
        "visibility": "visible",
        "label": "Company Name",
        "value": "CarryMe"
      },
      "ftp_username": {
        "visibility": "visible",
        "label": "FTP Username",
        "value": "foouser"
      },
      "ftp_password": {
        "visibility": "password",
        "label": "FTP Password",
        "value": "********"
      },
      "prioritytracked": {
        "visibility": "checkbox",
        "label": "Priority Tracked",
        "value": "1"
      },
      "pmi": {
        "visibility": "checkbox",
        "label": "PMI",
        "value": "0"
      },
      "epacket": {
        "visibility": "checkbox",
        "label": "ePacket",
        "value": "1"
      },
      "ipa": {
        "visibility": "checkbox",
        "label": "IPA",
        "value": "0"
      },
      "isal": {
        "visibility": "checkbox",
        "label": "ISAL",
        "value": "0"
      }
    }
  },
  "credentials": {
    "account_number": "12345",
    "company_name": "CarryMe",
    "ftp_username": "foouser",
    "ftp_password": "********",
    "prioritytracked": "1",
    "pmi": "0",
    "epacket": "1",
    "ipa": "0",
    "isal": "0"
  },
  "test_credentials": null
}
PUT /carrier_accounts/:id
Production Only This call will only work with your production API Key.

Update a Carrier Account

Updates can be made to description, reference, and any fields in credentials or test_credentials.

The CarrierType of the CarrierAccount should be consulted before attempting to updating an existing CarrierAccount, as it will inform you of the field names expected by a certain carrier.

Update Carrier Account Example


curl -X PUT https://api.easypost.com/v2/carrier_accounts/ca_... \
  -u <YOUR_PRODUCTION_API_KEY>: \
  -d 'carrier_account[description]=FL Location UPS Account' \
  -d 'carrier_account[credentials][account_number]=B2B2B2'

{
  "id": "ca_B0jH9G5c",
  "object": "CarrierAccount",
  "type": "UpsAccount",
  "description": "FL Location UPS Account",
  "clone": false,
  "created_at": "2016-01-13T01:00:01Z",
  "updated_at": "2016-01-13T01:00:01Z",
  "reference": "my-reference",
  "readable": "UPS",
  "logo": null,
  "fields": {
    "credentials": {
      "account_number": {
        "visibility": "visible",
        "label": "UPS Account Number",
        "value": "B2B2B2"
      },
      "access_license_number": {
        "visibility": "visible",
        "label": "UPS Access License Number",
        "value": "ALN"
      },
      "user_id": {
        "visibility": "visible",
        "label": "UPS.com User ID",
        "value": "USERID"
      },
      "password": {
        "visibility": "password",
        "label": "UPS.com Password",
        "value": "********"
      }
    }
  },
  "credentials": {
    "account_number": "B2B2B2",
    "user_id": "USERID",
    "password": "********",
    "access_license_number": "ALN"
  },
  "test_credentials": null
}
DELETE /carrier_accounts/:id
Production Only This call will only work with your production API Key.

Delete a Carrier Account

CarrierAccount objects may be removed from your account when they become out of date or no longer useful.

Delete Carrier Account Example


curl -X DELETE https://api.easypost.com/v2/carrier_accounts/ca_... \
  -u <YOUR_PRODUCTION_API_KEY>:

{ }