API Documentation

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 requires that all communication with the API is secured using TLS v1.2. 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.

Treat your API Keys as passwords—keep them secret. API Keys give full read/write access to your account, so they should not be included in public repositories, emails, client side code, etc. If yours gets leaked, you can disable it on the dashboard's API Keys Page.

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 Event which can contain many different types of result. For objects where there are many variant types, such as Fee, 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.

Full List of Error Codes

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

Pagination

Most "retrieve all" object responses from EasyPost are paginated. The request accepts a variety of parameters which can be used to modify the scope. The has_more attribute indicates whether or not additional pages can be requested. Records are returned in descending order (most recent first). The recommended way of paginating is to use either the before_id and after_id or start_datetime and end_datetime parameters to specify where the next page begins. Alternatively, you can use the optional page_size parameter that accepts an integer of how many records you would like per page. We limit the number of records per page to 100, most endpoints default to 20. Default page sizes and support for the before_id, after_id, start_datetime, and end_datetime parameters vary by endpoint.

If you need to retrieve a successive page when the has_more key is present, make another "retrieve all" request as before and set the before_id to the ID of the last item returned. Let's look at an example. If you were retrieving a shipment and your page_size was set to 20 but you had 140 results, there would be 7 pages of 20 results each. To get to page 2, you would need to set the before_id to the response['shipments'][19]['id']. To get to the next page, you would continue to request an additional page while specifying the last ID of the previous request. If you needed all results for a particular object, you would continue retrieving pages until the has_more key returns as false, indicating that all results have been retrieved.

Request Parameters

param	example	info
collection	shipments	A collection that contains a results page
page_size	30	The number of records to return on each page. The maximum value is 100, and default is 20.

Example

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Newtonsoft.Json;
using EasyPost;
using EasyPost.Models.API;
using EasyPost.Parameters;

namespace EasyPostExamples
{
    public class Examples
    {
        public static async Task Main()
        {
            string apiKey = Environment.GetEnvironmentVariable("EASYPOST_API_KEY")!;

            var client = new EasyPost.Client(apiKey);

            // Get first page of results
            Parameters.Shipment.All parameters = new()
            {
                PageSize = 5
            };

            ShipmentCollection shipmentCollection = await client.Shipment.All(parameters);

            // Provide the previous results page to move onto the next page
            ShipmentCollection nextPage = await client.Shipment.GetNextPage(shipmentCollection)

            Console.WriteLine(JsonConvert.SerializeObject(nextPage, Formatting.Indented));
        }
    }
}

{
  "shipments": [
    {
      "created_at": "2023-07-10T17:30:14Z",
      "is_return": false,
      "messages": [],
      "mode": "test",
      "options": {
        "currency": "USD",
        "payment": {
          "type": "SENDER"
        },
        "date_advance": 0
      },
      "reference": null,
      "status": "unknown",
      "tracking_code": "9400100105440232838888",
      "updated_at": "2023-07-10T17:30:16Z",
      "batch_id": null,
      "batch_status": null,
      "batch_message": null,
      "customs_info": {
        "id": "cstinfo_f85189b578ec4706ac387b76cec7ff01",
        "object": "CustomsInfo",
        "created_at": "2022-10-17T17:17:38Z",
        "updated_at": "2022-10-17T17:17:38Z",
        "contents_explanation": "",
        "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",
        "mode": "test",
        "declaration": null,
        "customs_items": [
          {
            "id": "cstitem_fa0aa9aa3a8f41639295c10aa7469480",
            "object": "CustomsItem",
            "created_at": "2022-10-17T17:17:38Z",
            "updated_at": "2022-10-17T17:17:38Z",
            "description": "T-shirt",
            "hs_tariff_number": "123456",
            "origin_country": "US",
            "quantity": 1,
            "value": "10.0",
            "weight": 5.0,
            "code": "123",
            "mode": "test",
            "manufacturer": null,
            "currency": null,
            "eccn": null,
            "printed_commodity_identifier": null
          }
        ]
      },
      "from_address": {
        "id": "adr_6e0ac14a1f4711eeacd5ac1f6bc539ae",
        "object": "Address",
        "created_at": "2023-07-10T17:30:14+00:00",
        "updated_at": "2023-07-10T17:30:14+00:00",
        "name": "EasyPost",
        "company": null,
        "street1": "417 Montgomery Street",
        "street2": "5th Floor",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94104",
        "country": "US",
        "phone": "4153334445",
        "email": "support@easypost.com",
        "mode": "test",
        "carrier_facility": null,
        "residential": null,
        "federal_tax_id": null,
        "state_tax_id": null,
        "verifications": {}
      },
      "insurance": null,
      "order_id": "order_2666c9282ad54765b74b9be1c0cccf09",
      "parcel": {
        "id": "prcl_2498d756b1c740b484f5665e5fdd697f",
        "object": "Parcel",
        "created_at": "2023-07-10T17:30:14Z",
        "updated_at": "2023-07-10T17:30:14Z",
        "length": null,
        "width": null,
        "height": null,
        "predefined_package": null,
        "weight": 10.2,
        "mode": "test"
      },
      "postage_label": {
        "object": "PostageLabel",
        "id": "pl_ce7b1a9249794cd697c87395d660d8f6",
        "created_at": "2023-07-10T17:30:15Z",
        "updated_at": "2023-07-10T17:30:16Z",
        "date_advance": 0,
        "integrated_form": "none",
        "label_date": "2023-07-10T17:30:15Z",
        "label_resolution": 300,
        "label_size": "4x6",
        "label_type": "default",
        "label_file_type": "image/png",
        "label_url": "https://easypost-files.s3.us-west-2.amazonaws.com/files/postage_label/20230710/e657608f44b6ec482c86742b7b8ea5d74d.png",
        "label_pdf_url": null,
        "label_zpl_url": null,
        "label_epl2_url": null,
        "label_file": null
      },
      "rates": [
        {
          "id": "rate_d669ba48a22b4f7f9a07939bf509de2a",
          "object": "Rate",
          "created_at": "2023-07-10T17:30:15Z",
          "updated_at": "2023-07-10T17:30:15Z",
          "mode": "test",
          "service": "Express",
          "carrier": "USPS",
          "rate": "31.25",
          "currency": "USD",
          "retail_rate": "35.80",
          "retail_currency": "USD",
          "list_rate": "31.25",
          "list_currency": "USD",
          "billing_type": "easypost",
          "delivery_days": null,
          "delivery_date": null,
          "delivery_date_guaranteed": false,
          "est_delivery_days": null,
          "shipment_id": "shp_06a2ad37dc1c425c88c593f3e9cf5ea4",
          "carrier_account_id": "ca_b25657e9896e4d63ac8151ac346ac41e"
        },
        {
          "id": "rate_ee0ba720bd6a4338b2945db6e450baba",
          "object": "Rate",
          "created_at": "2023-07-10T17:30:15Z",
          "updated_at": "2023-07-10T17:30:15Z",
          "mode": "test",
          "service": "Priority",
          "carrier": "USPS",
          "rate": "7.15",
          "currency": "USD",
          "retail_rate": "10.20",
          "retail_currency": "USD",
          "list_rate": "8.24",
          "list_currency": "USD",
          "billing_type": "easypost",
          "delivery_days": 2,
          "delivery_date": null,
          "delivery_date_guaranteed": false,
          "est_delivery_days": 2,
          "shipment_id": "shp_06a2ad37dc1c425c88c593f3e9cf5ea4",
          "carrier_account_id": "ca_b25657e9896e4d63ac8151ac346ac41e"
        },
        {
          "id": "rate_fd2144b885dd4725bfdf4ece351e9231",
          "object": "Rate",
          "created_at": "2023-07-10T17:30:15Z",
          "updated_at": "2023-07-10T17:30:15Z",
          "mode": "test",
          "service": "GroundAdvantage",
          "carrier": "USPS",
          "rate": "4.81",
          "currency": "USD",
          "retail_rate": "4.81",
          "retail_currency": "USD",
          "list_rate": "4.81",
          "list_currency": "USD",
          "billing_type": "easypost",
          "delivery_days": null,
          "delivery_date": null,
          "delivery_date_guaranteed": false,
          "est_delivery_days": null,
          "shipment_id": "shp_06a2ad37dc1c425c88c593f3e9cf5ea4",
          "carrier_account_id": "ca_b25657e9896e4d63ac8151ac346ac41e"
        },
        {
          "id": "rate_5dff1ed420df4a58833d9b47563565f6",
          "object": "Rate",
          "created_at": "2023-07-10T17:30:15Z",
          "updated_at": "2023-07-10T17:30:15Z",
          "mode": "test",
          "service": "First",
          "carrier": "USPS",
          "rate": "4.81",
          "currency": "USD",
          "retail_rate": "4.81",
          "retail_currency": "USD",
          "list_rate": "4.81",
          "list_currency": "USD",
          "billing_type": "easypost",
          "delivery_days": 3,
          "delivery_date": null,
          "delivery_date_guaranteed": false,
          "est_delivery_days": 3,
          "shipment_id": "shp_06a2ad37dc1c425c88c593f3e9cf5ea4",
          "carrier_account_id": "ca_b25657e9896e4d63ac8151ac346ac41e"
        }
      ],
      "refund_status": null,
      "scan_form": {
        "id": "sf_3684195c590740a88bc2c2cf5f25acb1",
        "object": "ScanForm",
        "created_at": "2022-10-17T17:17:39Z",
        "updated_at": "2022-10-17T17:17:40Z",
        "tracking_codes": ["9405500106068143632993"],
        "address": {
          "id": "adr_99962d534e3f11ed846dac1f6b0a0d1e",
          "object": "Address",
          "created_at": "2022-10-17T17:17:38+00:00",
          "updated_at": "2022-10-17T17:17:38+00:00",
          "name": "EasyPost",
          "company": null,
          "street1": "417 Montgomery Street",
          "street2": "5th Floor",
          "city": "San Francisco",
          "state": "CA",
          "zip": "94104",
          "country": "US",
          "phone": "4153334445",
          "email": "support@easypost.com",
          "mode": "test",
          "carrier_facility": null,
          "residential": null,
          "federal_tax_id": null,
          "state_tax_id": null,
          "verifications": {}
        },
        "status": "created",
        "message": null,
        "form_url": "https://easypost-files.s3.us-west-2.amazonaws.com/files/scan_form/20221017/58d6eef422424d02bd4105029666d614.pdf",
        "form_file_type": null,
        "batch_id": "batch_879633ae98a847409f0ca5b22c9872f4",
        "confirmation": null
      },
      "selected_rate": {
        "id": "rate_5dff1ed420df4a58833d9b47563565f6",
        "object": "Rate",
        "created_at": "2023-07-10T17:30:15Z",
        "updated_at": "2023-07-10T17:30:15Z",
        "mode": "test",
        "service": "First",
        "carrier": "USPS",
        "rate": "4.81",
        "currency": "USD",
        "retail_rate": "4.81",
        "retail_currency": "USD",
        "list_rate": "4.81",
        "list_currency": "USD",
        "billing_type": "easypost",
        "delivery_days": 3,
        "delivery_date": null,
        "delivery_date_guaranteed": false,
        "est_delivery_days": 3,
        "shipment_id": "shp_06a2ad37dc1c425c88c593f3e9cf5ea4",
        "carrier_account_id": "ca_b25657e9896e4d63ac8151ac346ac41e"
      },
      "tracker": {
        "id": "trk_1c56526a89e04c4c80013fd763f91228",
        "object": "Tracker",
        "mode": "test",
        "tracking_code": "9400100105440232838888",
        "status": "pre_transit",
        "status_detail": "status_update",
        "created_at": "2023-07-10T17:30:16Z",
        "updated_at": "2023-07-10T17:30:16Z",
        "signed_by": null,
        "weight": null,
        "est_delivery_date": "2023-07-10T17:30:16Z",
        "shipment_id": "shp_06a2ad37dc1c425c88c593f3e9cf5ea4",
        "carrier": "USPS",
        "tracking_details": [
          {
            "object": "TrackingDetail",
            "message": "Pre-Shipment Info Sent to USPS",
            "description": null,
            "status": "pre_transit",
            "status_detail": "status_update",
            "datetime": "2023-06-10T17:30:16Z",
            "source": "USPS",
            "carrier_code": null,
            "tracking_location": {
              "object": "TrackingLocation",
              "city": null,
              "state": null,
              "country": null,
              "zip": null
            }
          },
          {
            "object": "TrackingDetail",
            "message": "Shipping Label Created",
            "description": null,
            "status": "pre_transit",
            "status_detail": "status_update",
            "datetime": "2023-06-11T06:07:16Z",
            "source": "USPS",
            "carrier_code": null,
            "tracking_location": {
              "object": "TrackingLocation",
              "city": "HOUSTON",
              "state": "TX",
              "country": null,
              "zip": "77063"
            }
          }
        ],
        "fees": [],
        "carrier_detail": {
          "object": "CarrierDetail",
          "service": "First-Class Package Service",
          "container_type": null,
          "est_delivery_date_local": null,
          "est_delivery_time_local": null,
          "origin_location": "HOUSTON TX, 77001",
          "origin_tracking_location": {
            "object": "TrackingLocation",
            "city": "HOUSTON",
            "state": "TX",
            "country": null,
            "zip": "77063"
          },
          "destination_location": "CHARLESTON SC, 29401",
          "destination_tracking_location": null,
          "guaranteed_delivery_date": null,
          "alternate_identifier": null,
          "initial_delivery_attempt": null
        },
        "public_url": "https://track.easypost.com/djE6dHJrXzFjNTY1MjZhODllMDRjNGM4MDAxM2ZkNzYzZjkxMjI4"
      },
      "to_address": {
        "id": "adr_6e09528d1f4711ee9deaac1f6bc53342",
        "object": "Address",
        "created_at": "2023-07-10T17:30:14+00:00",
        "updated_at": "2023-07-10T17:30:15+00:00",
        "name": "DR. STEVE BRULE",
        "company": null,
        "street1": "179 N HARBOR DR",
        "street2": null,
        "city": "REDONDO BEACH",
        "state": "CA",
        "zip": "90277-2506",
        "country": "US",
        "phone": "8573875756",
        "email": "DR_STEVE_BRULE@GMAIL.COM",
        "mode": "test",
        "carrier_facility": null,
        "residential": false,
        "federal_tax_id": null,
        "state_tax_id": null,
        "verifications": {
          "zip4": {
            "success": true,
            "errors": [],
            "details": null
          },
          "delivery": {
            "success": true,
            "errors": [],
            "details": {
              "latitude": 33.8436,
              "longitude": -118.39177,
              "time_zone": "America/Los_Angeles"
            }
          }
        }
      },
      "usps_zone": 4,
      "return_address": {
        "id": "adr_6e0ac14a1f4711eeacd5ac1f6bc539ae",
        "object": "Address",
        "created_at": "2023-07-10T17:30:14+00:00",
        "updated_at": "2023-07-10T17:30:14+00:00",
        "name": "EasyPost",
        "company": null,
        "street1": "417 Montgomery Street",
        "street2": "5th Floor",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94104",
        "country": "US",
        "phone": "4153334445",
        "email": "support@easypost.com",
        "mode": "test",
        "carrier_facility": null,
        "residential": null,
        "federal_tax_id": null,
        "state_tax_id": null,
        "verifications": {}
      },
      "buyer_address": {
        "id": "adr_6e09528d1f4711ee9deaac1f6bc53342",
        "object": "Address",
        "created_at": "2023-07-10T17:30:14+00:00",
        "updated_at": "2023-07-10T17:30:15+00:00",
        "name": "DR. STEVE BRULE",
        "company": null,
        "street1": "179 N HARBOR DR",
        "street2": null,
        "city": "REDONDO BEACH",
        "state": "CA",
        "zip": "90277-2506",
        "country": "US",
        "phone": "8573875756",
        "email": "DR_STEVE_BRULE@GMAIL.COM",
        "mode": "test",
        "carrier_facility": null,
        "residential": false,
        "federal_tax_id": null,
        "state_tax_id": null,
        "verifications": {
          "zip4": {
            "success": true,
            "errors": [],
            "details": null
          },
          "delivery": {
            "success": true,
            "errors": [],
            "details": {
              "latitude": 33.8436,
              "longitude": -118.39177,
              "time_zone": "America/Los_Angeles"
            }
          }
        }
      },
      "forms": [],
      "fees": [
        {
          "object": "Fee",
          "type": "LabelFee",
          "amount": "0.00000",
          "charged": true,
          "refunded": false
        },
        {
          "object": "Fee",
          "type": "PostageFee",
          "amount": "4.81000",
          "charged": true,
          "refunded": false
        }
      ],
      "id": "shp_06a2ad37dc1c425c88c593f3e9cf5ea4",
      "object": "Shipment"
    }
  ],
  "has_more": false
}

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
details	VerificationDetails	Extra data related to the verification

VerificationDetails Object

attribute	type	specification
latitude	number	The latitude
longitude	number	The longitude
time_zone	TZ(string)	The time zone the address is located in, IE: America/Los_Angeles

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 providing verify or verify_strict in the parameters. If any of the strict verification checks fail, an error will be returned from the API. The example below demonstrates verifying 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.

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	true	Include to perform verifications on delivery and zip code. verify_strict takes precedence if also included.
verify_strict	true	Include to perform strict verifications on delivery and zip code. The failure of any of these verifications causes the whole request to fail.

Example

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Newtonsoft.Json;
using EasyPost;
using EasyPost.Models.API;
using EasyPost.Parameters;

namespace EasyPostExamples
{
    public class Examples
    {
        public static async Task Main()
        {
            string apiKey = Environment.GetEnvironmentVariable("EASYPOST_API_KEY")!;

            var client = new EasyPost.Client(apiKey);

            Parameters.Address.Create parameters = new()
            {
                Street1 = "417 MONTGOMERY ST",
                Street2 = "FLOOR 5",
                City = "SAN FRANCISCO",
                State = "CA",
                Zip = "94104",
                Country = "US",
                Company = "EasyPost",
                Phone = "415-123-4567",
            };

            Address address = await client.Address.Create(parameters);

            Console.WriteLine(JsonConvert.SerializeObject(address, Formatting.Indented));
        }
    }
}

{
  "id": "adr_5dacbea44e3f11ed90f5ac1f6bc72124",
  "object": "Address",
  "created_at": "2022-10-17T17:15:57+00:00",
  "updated_at": "2022-10-17T17:15:57+00:00",
  "name": null,
  "company": "EasyPost",
  "street1": "417 MONTGOMERY ST",
  "street2": "FLOOR 5",
  "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": {}
}

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Newtonsoft.Json;
using EasyPost;
using EasyPost.Models.API;
using EasyPost.Parameters;

namespace EasyPostExamples
{
    public class Examples
    {
        public static async Task Main()
        {
            string apiKey = Environment.GetEnvironmentVariable("EASYPOST_API_KEY")!;

            var client = new EasyPost.Client(apiKey);

            Parameters.Address.Create parameters = new()
            {
                Street1 = "417 Montgomery Street",
                Street2 = "FL 5",
                City = "San Francisco",
                State = "CA",
                Zip = "94104",
                Country = "US",
                Company = "EasyPost",
                Phone = "415-123-4567",
            };

            Address address = await client.Address.CreateAndVerify(parameters);

            Console.WriteLine(JsonConvert.SerializeObject(address, Formatting.Indented));
        }
    }
}

{
  "address": {
    "id": "adr_5e891acf4e3f11edb1a1ac1f6bc7bdc6",
    "object": "Address",
    "created_at": "2022-10-17T17:15:59+00:00",
    "updated_at": "2022-10-17T17:15:59+00:00",
    "name": null,
    "company": "EASYPOST",
    "street1": "417 MONTGOMERY ST FL 5",
    "street2": "",
    "city": "SAN FRANCISCO",
    "state": "CA",
    "zip": "94104-1129",
    "country": "US",
    "phone": "4151234567",
    "email": null,
    "mode": "test",
    "carrier_facility": null,
    "residential": false,
    "federal_tax_id": null,
    "state_tax_id": null,
    "verifications": {
      "zip4": {
        "success": true,
        "errors": [
          {
            "code": "E.SECONDARY_INFORMATION.INVALID",
            "field": "street2",
            "message": "Invalid secondary information(Apt/Suite#)",
            "suggestion": null
          }
        ],
        "details": null
      },
      "delivery": {
        "success": true,
        "errors": [
          {
            "code": "E.SECONDARY_INFORMATION.INVALID",
            "field": "street2",
            "message": "Invalid secondary information(Apt/Suite#)",
            "suggestion": null
          }
        ],
        "details": {
          "latitude": 37.79342,
          "longitude": -122.40288,
          "time_zone": "America/Los_Angeles"
        }
      }
    }
  }
}

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Newtonsoft.Json;
using EasyPost;
using EasyPost.Models.API;
using EasyPost.Parameters;

namespace EasyPostExamples
{
    public class Examples
    {
        public static async Task Main()
        {
            string apiKey = Environment.GetEnvironmentVariable("EASYPOST_API_KEY")!;

            var client = new EasyPost.Client(apiKey);

            Parameters.Address.Create parameters = new()
            {
                Street1 = "417 MONTGOMERY ST",
                Street2 = "FLOOR 5",
                City = "SAN FRANCISCO",
                State = "CA",
                Zip = "94104",
                Country = "US",
                Company = "EasyPost",
                Phone = "415-123-4567",
                Verify = true
            };

            Address address = await client.Address.Create(parameters);

            Console.WriteLine(JsonConvert.SerializeObject(address, Formatting.Indented));
        }
    }
}

{
  "id": "adr_5eed63904e3f11eda352ac1f6bc7b362",
  "object": "Address",
  "created_at": "2022-10-17T17:16:00+00:00",
  "updated_at": "2022-10-17T17:16:00+00:00",
  "name": null,
  "company": "EASYPOST",
  "street1": "417 MONTGOMERY ST FL 5",
  "street2": "",
  "city": "SAN FRANCISCO",
  "state": "CA",
  "zip": "94104-1129",
  "country": "US",
  "phone": "4151234567",
  "email": null,
  "mode": "test",
  "carrier_facility": null,
  "residential": false,
  "federal_tax_id": null,
  "state_tax_id": null,
  "verifications": {
    "zip4": {
      "success": true,
      "errors": [
        {
          "code": "E.SECONDARY_INFORMATION.INVALID",
          "field": "street2",
          "message": "Invalid secondary information(Apt/Suite#)",
          "suggestion": null
        }
      ],
      "details": null
    },
    "delivery": {
      "success": true,
      "errors": [
        {
          "code": "E.SECONDARY_INFORMATION.INVALID",
          "field": "street2",
          "message": "Invalid secondary information(Apt/Suite#)",
          "suggestion": null
        }
      ],
      "details": {
        "latitude": 37.79342,
        "longitude": -122.40288,
        "time_zone": "America/Los_Angeles"
      }
    }
  }
}

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Newtonsoft.Json;
using EasyPost;
using EasyPost.Models.API;
using EasyPost.Parameters;

namespace EasyPostExamples
{
    public class Examples
    {
        public static async Task Main()
        {
            string apiKey = Environment.GetEnvironmentVariable("EASYPOST_API_KEY")!;

            var client = new EasyPost.Client(apiKey);

            Parameters.Address.Create parameters = new()
            {
                Street1 = "UNDELIVERABLE ST",
                Street2 = "FLOOR 5",
                City = "SAN FRANCISCO",
                State = "CA",
                Zip = "94104",
                Country = "US",
                Company = "EasyPost",
                Phone = "415-123-4567",
            };

            Address address = await client.Address.Create(parameters);

            Console.WriteLine(JsonConvert.SerializeObject(address, Formatting.Indented));
        }
    }
}

{
  "id": "adr_20a96bfd554911ed9551ac1f6bc72124",
  "object": "Address",
  "created_at": "2022-10-26T16:13:28+00:00",
  "updated_at": "2022-10-26T16:13:28+00:00",
  "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": {
    "zip4": {
      "success": false,
      "errors": [
        {
          "code": "E.ADDRESS.NOT_FOUND",
          "field": "address",
          "message": "Address not found",
          "suggestion": null
        },
        {
          "code": "E.HOUSE_NUMBER.MISSING",
          "field": "street1",
          "message": "House number is missing",
          "suggestion": null
        }
      ],
      "details": null
    },
    "delivery": {
      "success": false,
      "errors": [
        {
          "code": "E.ADDRESS.NOT_FOUND",
          "field": "address",
          "message": "Address not found",
          "suggestion": null
        },
        {
          "code": "E.HOUSE_NUMBER.MISSING",
          "field": "street1",
          "message": "House number is missing",
          "suggestion": null
        }
      ],
      "details": {}
    }
  }
}

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Newtonsoft.Json;
using EasyPost;
using EasyPost.Models.API;
using EasyPost.Parameters;

namespace EasyPostExamples
{
    public class Examples
    {
        public static async Task Main()
        {
            string apiKey = Environment.GetEnvironmentVariable("EASYPOST_API_KEY")!;

            var client = new EasyPost.Client(apiKey);

            Parameters.Address.Create parameters = new()
            {
                Street1 = "417 MONTGOMERY ST",
                Street2 = "FLOOR 5",
                City = "SAN FRANCISCO",
                State = "CA",
                Zip = "94104",
                Country = "US",
                Company = "EasyPost",
                Phone = "415-123-4567",
                VerifyStrict = true
            };

            Address address = await client.Address.Create(parameters);

            Console.WriteLine(JsonConvert.SerializeObject(address, Formatting.Indented));
        }
    }
}

{
  "id": "adr_5f4e008e4e3f11eda36cac1f6bc7b362",
  "object": "Address",
  "created_at": "2022-10-17T17:16:00+00:00",
  "updated_at": "2022-10-17T17:16:00+00:00",
  "name": null,
  "company": "EASYPOST",
  "street1": "417 MONTGOMERY ST FL 5",
  "street2": "",
  "city": "SAN FRANCISCO",
  "state": "CA",
  "zip": "94104-1129",
  "country": "US",
  "phone": "4151234567",
  "email": null,
  "mode": "test",
  "carrier_facility": null,
  "residential": false,
  "federal_tax_id": null,
  "state_tax_id": null,
  "verifications": {
    "zip4": {
      "success": true,
      "errors": [
        {
          "code": "E.SECONDARY_INFORMATION.INVALID",
          "field": "street2",
          "message": "Invalid secondary information(Apt/Suite#)",
          "suggestion": null
        }
      ],
      "details": null
    },
    "delivery": {
      "success": true,
      "errors": [
        {
          "code": "E.SECONDARY_INFORMATION.INVALID",
          "field": "street2",
          "message": "Invalid secondary information(Apt/Suite#)",
          "suggestion": null
        }
      ],
      "details": {
        "latitude": 37.79342,
        "longitude": -122.40288,
        "time_zone": "America/Los_Angeles"
      }
    }
  }
}

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Newtonsoft.Json;
using EasyPost;
using EasyPost.Models.API;
using EasyPost.Parameters;

namespace EasyPostExamples
{
    public class Examples
    {
        public static async Task Main()
        {
            string apiKey = Environment.GetEnvironmentVariable("EASYPOST_API_KEY")!;

            var client = new EasyPost.Client(apiKey);

            Parameters.Address.Create parameters = new()
            {
                Street1 = "417 MONTGOMERY ST",
                Street2 = "FLOOR 5",
                City = "SAN FRANCISCO",
                State = "CA",
                Zip = "94104",
                Country = "US",
                Company = "EasyPost",
                Phone = "415-123-4567",
            };

            Address address = await client.Address.Create(parameters);

            address = await client.Address.Verify(address.Id)

            Console.WriteLine(JsonConvert.SerializeObject(address, Formatting.Indented));
        }
    }
}

{
  "address": {
    "id": "adr_5fdd21764e3f11edadebac1f6b0a0d1e",
    "object": "Address",
    "created_at": "2022-10-17T17:16:01+00:00",
    "updated_at": "2022-10-17T17:16:01+00:00",
    "name": null,
    "company": "EASYPOST",
    "street1": "417 MONTGOMERY ST FL 5",
    "street2": "",
    "city": "SAN FRANCISCO",
    "state": "CA",
    "zip": "94104-1129",
    "country": "US",
    "phone": "4151234567",
    "email": null,
    "mode": "test",
    "carrier_facility": null,
    "residential": false,
    "federal_tax_id": null,
    "state_tax_id": null,
    "verifications": {
      "zip4": {
        "success": true,
        "errors": [
          {
            "code": "E.SECONDARY_INFORMATION.INVALID",
            "field": "street2",
            "message": "Invalid secondary information(Apt/Suite#)",
            "suggestion": null
          }
        ],
        "details": null
      },
      "delivery": {
        "success": true,
        "errors": [
          {
            "code": "E.SECONDARY_INFORMATION.INVALID",
            "field": "street2",
            "message": "Invalid secondary information(Apt/Suite#)",
            "suggestion": null
          }
        ],
        "details": {
          "latitude": 37.79342,
          "longitude": -122.40288,
          "time_zone": "America/Los_Angeles"
        }
      }
    }
  }
}

GET/addresses

Retrieve a list of Addresses

The Address List is a paginated list of all Address objects associated with the given API Key. See the Pagination section of our docs for more details on retrieving all records when multiple pages are available.

Request Parameters

param	example	info
page_size	30	The number of records to return on each page. The maximum value is 100, and default is 20.

Example

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Newtonsoft.Json;
using EasyPost;
using EasyPost.Models.API;
using EasyPost.Parameters;

namespace EasyPostExamples
{
    public class Examples
    {
        public static async Task Main()
        {
            string apiKey = Environment.GetEnvironmentVariable("EASYPOST_API_KEY")!;

            var client = new EasyPost.Client(apiKey);

            Parameters.Address.All parameters = new()
            {
                PageSize = 5
            };

            AddressCollection addressCollection = await client.Address.All(parameters);

            Console.WriteLine(JsonConvert.SerializeObject(addressCollection, Formatting.Indented));
        }
    }
}

{
  "addresses": [
    {
      "id": "adr_6039af864e3f11edae1dac1f6b0a0d1e",
      "object": "Address",
      "created_at": "2022-10-17T17:16:02+00:00",
      "updated_at": "2022-10-17T17:16:02+00:00",
      "name": null,
      "company": "EasyPost",
      "street1": "417 MONTGOMERY ST",
      "street2": "FLOOR 5",
      "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": {}
    }
  ],
  "has_more": true
}

GET/addresses/:id

Retrieve an Address

An Address can be retrieved by its id.

Example

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Newtonsoft.Json;
using EasyPost;
using EasyPost.Models.API;

namespace EasyPostExamples
{
    public class Examples
    {
        public static async Task Main()
        {
            string apiKey = Environment.GetEnvironmentVariable("EASYPOST_API_KEY")!;

            var client = new EasyPost.Client(apiKey);

            Address address = await client.Address.Retrieve("adr_...");

            Console.WriteLine(JsonConvert.SerializeObject(address, Formatting.Indented));
        }
    }
}

{
  "id": "adr_6039af864e3f11edae1dac1f6b0a0d1e",
  "object": "Address",
  "created_at": "2022-10-17T17:16:02+00:00",
  "updated_at": "2022-10-17T17:16:02+00:00",
  "name": null,
  "company": "EasyPost",
  "street1": "417 MONTGOMERY ST",
  "street2": "FLOOR 5",
  "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": {}
}

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. Only weight is required, but since many carriers charge different rates for packages with large dimensions, we strongly recommend including all dimensions if available.

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 width and/or height are present
width	float(inches)	Required if width and/or height are present
height	float(inches)	Required if width and/or height are present
predefined_package	string	Optional, one of our predefined_packages
weight	float(oz)	Always required
created_at	datetime
updated_at	datetime

Predefined Packages

If you provide a predefined_package the associated Shipment will fetch rates from carriers for which that is a valid predefined_package. Some carriers share predefined_package names. If you wish to restrict your rating to a specific carrier, we recommend passing the carrier_accounts field when creating a Shipment.

For most predefined_packages it is not necessary to specify parcel dimensions, only weight.

No predefined packages for Amazon MWS.

No predefined packages for APC.

No predefined packages for Asendia USA.

CARTON
PALLET
SATCHEL
BAG
ENVELOPE
ITEM
JIFFYBAG
SKID

No predefined packages for AxlehireV3.

No predefined packages for Better Trucks.

No predefined packages for Canada Post.

No predefined packages for Canpar.

No predefined packages for CDL Last Mile Solutions.

No predefined packages for Chronopost.

No predefined packages for Cirro E-Commerce.

No predefined packages for CloudSort.

No predefined packages for Courier Express.

No predefined packages for Couriers Please.

No predefined packages for DAI Post.

No predefined packages for Deliver-It.

No predefined packages for Deutsche Post.

No predefined packages for Deutsche Post UK.

No predefined packages for DHL eCommerce Solutions.

JumboDocument
JumboParcel
Document
DHLFlyer
Domestic
ExpressDocument
DHLExpressEnvelope
JumboBox
JumboJuniorDocument
JuniorJumboBox
JumboJuniorParcel
OtherDHLPackaging
Parcel
YourPackaging

No predefined packages for DHL Paket.

No predefined packages for DHL SmartMail.

No predefined packages for DPD.

No predefined packages for DPD NL.

Parcel
Pallet
ExpressPak
FreightParcel
Freight

No predefined packages for ePostGlobal.

ENVELOPE
PARCEL

No predefined packages for Evri.

Parcel
A2
A3
A4
A5
BOXSML
BOXMED
BOXLRG

FedExEnvelope
FedExBox
FedExPak
FedExTube
FedEx10kgBox
FedEx25kgBox
FedExSmallBox
FedExMediumBox
FedExLargeBox
FedExExtraLargeBox

No predefined packages for FedEx Ground Economy.

No predefined packages for FedEx Mailview.

No predefined packages for First Mile.

No predefined packages for Flexport.

No predefined packages for GSO.

No predefined packages for Hailify.

Parcel
Pallet
ExpressPak
FreightParcel
Freight

No predefined packages for JP Post.

No predefined packages for Kuroneko Yamato.

No predefined packages for La Poste.

Envelope
Custom

No predefined packages for Loomis Express.

No predefined packages for LSO.

No predefined packages for Maergo.

No predefined packages for Newgistics.

Letter

No predefined packages for Optima.

parcel
irregularparcel
softpack

No predefined packages for Pandion.

No predefined packages for Parcelforce.

No predefined packages for Passport.

No predefined packages for PostNL.

CUSTOMERPACKAGING
EXPRESSPACK
EXPRESSBOX
EXPRESSENVELOPE

LARGELETTER
SMALLPARCEL
MEDIUMPARCEL
LETTER
PRINTEDPAPER

Bag
Box
Carton
Container
Crate
Envelope
Pail
Pallet
Satchel
Tub

No predefined packages for Sendle.

No predefined packages for SF Express.

No predefined packages for SmartKargo.

No predefined packages for Sonic.

No predefined packages for Spee-Dee.

No predefined packages for Swyft.

No predefined packages for TForce Logistics.

No predefined packages for Toll.

No predefined packages for UDS.

UPSLetter
UPSExpressBox
UPS25kgBox
UPS10kgBox
Tube
Pak
SmallExpressBox
MediumExpressBox
LargeExpressBox

No predefined packages for UPS iParcel.

No predefined packages for UPS Mail Innovations.

USPS Flat Rate Mapping USPS Package Restrictions

Card
Letter
Flat
FlatRateEnvelope
FlatRateLegalEnvelope
FlatRatePaddedEnvelope
FlatRateWindowEnvelope
FlatRateCardboardEnvelope
SmallFlatRateEnvelope
Parcel
SoftPack
SmallFlatRateBox
MediumFlatRateBox
LargeFlatRateBox
LargeFlatRateBoxAPOFPO
FlatTubTrayBox
EMMTrayBox
FullTrayBox
HalfTrayBox
PMODSack

No predefined packages for Veho.

No predefined packages for Yanwen.

POST/parcels

Create a Parcel

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

Request Parameters

param	example
length	20.2
width	10.9
height	5
weight	65.9

Example

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Newtonsoft.Json;
using EasyPost;
using EasyPost.Models.API;
using EasyPost.Parameters;

namespace EasyPostExamples
{
    public class Examples
    {
        public static async Task Main()
        {
            string apiKey = Environment.GetEnvironmentVariable("EASYPOST_API_KEY")!;

            var client = new EasyPost.Client(apiKey);

            Parameters.Parcel.Create parameters = new()
            {
                Length = 20.2,
                Width = 10.9,
                Height = 5,
                Weight = 65.9
            };

            Parcel parcel = await client.Parcel.Create(parameters);

            Console.WriteLine(JsonConvert.SerializeObject(parcel, Formatting.Indented));
        }
    }
}

{
  "id": "prcl_f1e15ba5892749e2a039a70b4d83d5d1",
  "object": "Parcel",
  "created_at": "2022-10-17T17:17:08Z",
  "updated_at": "2022-10-17T17:17:08Z",
  "length": 20.2,
  "width": 10.9,
  "height": 5.0,
  "predefined_package": null,
  "weight": 65.9,
  "mode": "test"
}

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.

Example

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Newtonsoft.Json;
using EasyPost;
using EasyPost.Models.API;

namespace EasyPostExamples
{
    public class Examples
    {
        public static async Task Main()
        {
            string apiKey = Environment.GetEnvironmentVariable("EASYPOST_API_KEY")!;

            var client = new EasyPost.Client(apiKey);

            Parcel parcel = await client.Parcel.Retrieve("prcl_...");

            Console.WriteLine(JsonConvert.SerializeObject(parcel, Formatting.Indented));
        }
    }
}

{
  "id": "prcl_76ca5e21f413474bad2ae2086ba902ae",
  "object": "Parcel",
  "created_at": "2022-10-17T17:17:08Z",
  "updated_at": "2022-10-17T17:17:08Z",
  "length": 20.2,
  "width": 10.9,
  "height": 5.0,
  "predefined_package": null,
  "weight": 65.9,
  "mode": "test"
}

Insurances

An Insurance object represents insurance for packages purchased both via the EasyPost API as well as shipments purchased through third parties and later registered with EasyPost. An Insurance is created automatically whenever you buy a Shipment through EasyPost and pass insurance options during the Buy call or in a later call to Insure a Shipment.

Insurance purchased through the Shipment Buy or Insure endpoints is immediately insured - there is no possibility of rejection based on tracking information, as the package was just created. On the other hand, Insurance purchased on shipments purchased outside of EasyPost requires creation with a tracking code so that EasyPost may confirm the package existence and current shipping status at the time of purchase.

Standalone insurance is created in a pending state to help distinguish it from insurance purchased for an EasyPost Shipment. Both kinds of Insurance use the Tracking system to receive periodic updates, and will report those updates to any appropriate Webhook on file. Standalone insurance will cancel itself if the tracking information for the given tracking code shows evidence of having been shipped anytime before the insurance was purchased.

Unlike Shipments within EasyPost, Insurance objects register To and From Address objects according to the destination and ship-from locations of the package. This means that a Shipment with "is_return: true" actually ships to the listed From Address. Insurance does not have a concept of "is_return", so all insurance records refer to their true package destination as "to_address", regardless of whether or not the shipment is a return.

Insurance Object

attribute	type	specification
id	string	Unique identifier, begins with "ins_"
object	string	"Insurance"
mode	string	"test" or "production"
reference	string	The reference for this Insurance, if any
amount	string	USD value of insured goods with sub-cent precision
provider	string	The insurance provider used by EasyPost
provider_id	string	An identifying number for some insurance providers used by EasyPost
shipment_id	string	The ID of the Shipment in EasyPost, if postage was purchased via EasyPost
tracking_code	string	The tracking code of either the shipment within EasyPost, or provided by you during creation
status	string	The current status of the insurance, possible values are "new", "pending", "purchased", "failed", or "cancelled"
tracker	Tracker	The associated Tracker object
to_address	Address	The associated Address object for destination (optional)
from_address	Address	The associated Address object for origin (optional)
fee	Fee	The associated InsuranceFee object if any
messages	Array of strings	The list of errors encountered during attempted purchase of the insurance
created_at	datetime
updated_at	datetime

POST/insurances

Create an Insurance

An Insurance created via this endpoint must belong to a shipment purchased outside of EasyPost. Insurance for Shipments created within EasyPost must be created via the Shipment Buy or Insure endpoints. When creating Insurance for a non-EasyPost shipment, you must provide tracking_code and amount information. Optionally, you can provide the carrier parameter, which will help EasyPost identify 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.

Customers must have their own FedEx account to insure FedEx packages.

Request Parameters

param	example	info
to_address	Address	The destination of the package to be insured (optional).
from_address	Address	The origin of the package to be insured (optional).
tracking_code	9400110898825022579493	The tracking code associated with the non-EasyPost-purchased package you'd like to insure.
reference	external-order-493	An optional value that may be used in place of ID when doing Retrieve calls for this insurance.
amount	"$100.00"	The USD value of contents you would like to insure. Currently the maximum is $5000.
carrier	USPS	The carrier associated with the tracking_code you provided. The carrier will get auto-detected if none is provided.

Example

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Newtonsoft.Json;
using EasyPost;
using EasyPost.Models.API;
using EasyPost.Parameters;

namespace EasyPostExamples
{
    public class Examples
    {
        public static async Task Main()
        {
            string apiKey = Environment.GetEnvironmentVariable("EASYPOST_API_KEY")!;

            var client = new EasyPost.Client(apiKey);

            Parameters.Insurance.Create parameters = new()
            {
                Amount = 100.00,
                Carrier = "USPS",
                TrackingCode = "9400110898825022579493",
                ToAddress = new Parameters.Address.Create
                {
                    Name = "Dr. Steve Brule",
                    Street1 = "417 Montgomery Street",
                    Street2 = "5th Floor",
                    City = "San Francisco",
                    State = "CA",
                    Country = "US",
                    Zip = "94104"
                },
                FromAddress = new Parameters.Address.Create
                {
                    Company = "EasyPost",
                    Street1 = "417 Montgomery Street",
                    Street2 = "Floor 5",
                    City = "San Francisco",
                    State = "CA",
                    Country = "US",
                    Zip = "94104"
                }
            };

            Insurance insurance = await client.Insurance.Create(parameters);

            Console.WriteLine(JsonConvert.SerializeObject(insurance, Formatting.Indented));
        }
    }
}

{
  "id": "ins_7609b3212565474389a311ce8ff70c78",
  "object": "Insurance",
  "mode": "test",
  "reference": null,
  "status": "pending",
  "amount": "100.00000",
  "provider": "easypost",
  "provider_id": null,
  "to_address": {
    "id": "adr_e0e4047f4e4311ed9b74ac1f6bc7b362",
    "object": "Address",
    "created_at": "2022-10-17T17:48:16+00:00",
    "updated_at": "2022-10-17T17:48:16+00:00",
    "name": "DR. STEVE BRULE",
    "company": null,
    "street1": "179 N HARBOR DR",
    "street2": "",
    "city": "REDONDO BEACH",
    "state": "CA",
    "zip": "90277-2506",
    "country": "US",
    "phone": "8573875756",
    "email": "DR_STEVE_BRULE@GMAIL.COM",
    "mode": "test",
    "carrier_facility": null,
    "residential": false,
    "federal_tax_id": null,
    "state_tax_id": null,
    "verifications": {
      "zip4": {
        "success": true,
        "errors": [],
        "details": null
      },
      "delivery": {
        "success": true,
        "errors": [],
        "details": {
          "latitude": 33.8436,
          "longitude": -118.39177,
          "time_zone": "America/Los_Angeles"
        }
      }
    }
  },
  "from_address": {
    "id": "adr_e0e89e564e4311eda48eac1f6b0a0d1e",
    "object": "Address",
    "created_at": "2022-10-17T17:48:16+00:00",
    "updated_at": "2022-10-17T17:48:16+00:00",
    "name": "EASYPOST",
    "company": null,
    "street1": "417 MONTGOMERY ST # 5",
    "street2": "",
    "city": "SAN FRANCISCO",
    "state": "CA",
    "zip": "94104-1129",
    "country": "US",
    "phone": "4153334445",
    "email": "SUPPORT@EASYPOST.COM",
    "mode": "test",
    "carrier_facility": null,
    "residential": false,
    "federal_tax_id": null,
    "state_tax_id": null,
    "verifications": {
      "zip4": {
        "success": true,
        "errors": [
          {
            "code": "E.SECONDARY_INFORMATION.INVALID",
            "field": "street2",
            "message": "Invalid secondary information(Apt/Suite#)",
            "suggestion": null
          }
        ],
        "details": null
      },
      "delivery": {
        "success": true,
        "errors": [
          {
            "code": "E.SECONDARY_INFORMATION.INVALID",
            "field": "street2",
            "message": "Invalid secondary information(Apt/Suite#)",
            "suggestion": null
          }
        ],
        "details": {
          "latitude": 37.79342,
          "longitude": -122.40288,
          "time_zone": "America/Los_Angeles"
        }
      }
    }
  },
  "shipment_id": null,
  "tracker": null,
  "tracking_code": "9400110898825022579493",
  "fee": {
    "object": "Fee",
    "type": "InsuranceFee",
    "amount": "0.50000",
    "charged": true,
    "refunded": false
  },
  "messages": [],
  "created_at": "2022-10-17T17:48:16Z",
  "updated_at": "2022-10-17T17:48:16Z"
}

GET/insurances

Retrieve a list of Insurances

The Insurance List is a paginated list of all Insurance objects associated with the given API Key. See the Pagination section of our docs for more details on retrieving all records when multiple pages are available.

Request Parameters

param	example	info
before_id	ins_...	Optional pagination parameter. Only records created before the given ID will be included. May not be used with after_id
after_id	ins_...	Optional pagination parameter. Only records created after the given ID will be included. May not be used with before_id
start_datetime	2016-01-02T00:00:00Z	Only return records 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 records 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 records to return on each page. The maximum value is 100, and default is 20.

Example

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Newtonsoft.Json;
using EasyPost;
using EasyPost.Models.API;
using EasyPost.Parameters;

namespace EasyPostExamples
{
    public class Examples
    {
        public static async Task Main()
        {
            string apiKey = Environment.GetEnvironmentVariable("EASYPOST_API_KEY")!;

            var client = new EasyPost.Client(apiKey);

            Parameters.Insurance.All parameters = new()
            {
                PageSize = 5
            };

            InsuranceCollection insuranceCollection = await client.Insurance.All(parameters);

            Console.WriteLine(JsonConvert.SerializeObject(insuranceCollection, Formatting.Indented));
        }
    }
}

{
  "insurances": [
    {
      "id": "ins_eb937fd125c4495986d33ab14d175952",
      "object": "Insurance",
      "mode": "test",
      "reference": "insuranceRef1",
      "status": "pending",
      "amount": "100.00000",
      "provider": "easypost",
      "provider_id": null,
      "to_address": {
        "id": "adr_91a042464be811ed9d0fac1f6b0a0d1e",
        "object": "Address",
        "created_at": "2022-10-14T17:49:36+00:00",
        "updated_at": "2022-10-14T17:49:36+00:00",
        "name": "DR. STEVE BRULE",
        "company": null,
        "street1": "179 N HARBOR DR",
        "street2": null,
        "city": "REDONDO BEACH",
        "state": "CA",
        "zip": "90277-2506",
        "country": "US",
        "phone": "8573875756",
        "email": "DR_STEVE_BRULE@GMAIL.COM",
        "mode": "test",
        "carrier_facility": null,
        "residential": false,
        "federal_tax_id": null,
        "state_tax_id": null,
        "verifications": {
          "zip4": {
            "success": true,
            "errors": [],
            "details": null
          },
          "delivery": {
            "success": true,
            "errors": [],
            "details": {
              "latitude": 33.8436,
              "longitude": -118.39177,
              "time_zone": "America/Los_Angeles"
            }
          }
        }
      },
      "from_address": {
        "id": "adr_91a4575b4be811edab5aac1f6bc7b362",
        "object": "Address",
        "created_at": "2022-10-14T17:49:36+00:00",
        "updated_at": "2022-10-14T17:49:36+00:00",
        "name": "EASYPOST",
        "company": null,
        "street1": "417 MONTGOMERY ST # 5",
        "street2": null,
        "city": "SAN FRANCISCO",
        "state": "CA",
        "zip": "94104-1129",
        "country": "US",
        "phone": "4153334445",
        "email": "SUPPORT@EASYPOST.COM",
        "mode": "test",
        "carrier_facility": null,
        "residential": false,
        "federal_tax_id": null,
        "state_tax_id": null,
        "verifications": {
          "zip4": {
            "success": true,
            "errors": [
              {
                "code": "E.SECONDARY_INFORMATION.INVALID",
                "field": "street2",
                "message": "Invalid secondary information(Apt/Suite#)",
                "suggestion": null
              }
            ],
            "details": null
          },
          "delivery": {
            "success": true,
            "errors": [
              {
                "code": "E.SECONDARY_INFORMATION.INVALID",
                "field": "street2",
                "message": "Invalid secondary information(Apt/Suite#)",
                "suggestion": null
              }
            ],
            "details": {
              "latitude": 37.79342,
              "longitude": -122.40288,
              "time_zone": "America/Los_Angeles"
            }
          }
        }
      },
      "shipment_id": null,
      "tracker": null,
      "tracking_code": "9400110898825022579493",
      "fee": {
        "object": "Fee",
        "type": "InsuranceFee",
        "amount": "0.50000",
        "charged": true,
        "refunded": false
      },
      "messages": [],
      "created_at": "2022-10-14T17:49:36Z",
      "updated_at": "2022-10-14T17:49:36Z"
    }
  ],
  "has_more": false
}

GET/insurances/:id

Retrieve an Insurance

Retrieve an Insurance by id.

Request Parameters

param	example	info
id	ins_...	Unique, starts with "ins_"

Example

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Newtonsoft.Json;
using EasyPost;
using EasyPost.Models.API;

namespace EasyPostExamples
{
    public class Examples
    {
        public static async Task Main()
        {
            string apiKey = Environment.GetEnvironmentVariable("EASYPOST_API_KEY")!;

            var client = new EasyPost.Client(apiKey);

            Insurance insurance = await client.Insurance.Retrieve("ins_...");

            Console.WriteLine(JsonConvert.SerializeObject(insurance, Formatting.Indented));
        }
    }
}

{
  "id": "ins_eb937fd125c4495986d33ab14d175952",
  "object": "Insurance",
  "mode": "test",
  "reference": "insuranceRef1",
  "status": "pending",
  "amount": "100.00000",
  "provider": "easypost",
  "provider_id": null,
  "to_address": {
    "id": "adr_91a042464be811ed9d0fac1f6b0a0d1e",
    "object": "Address",
    "created_at": "2022-10-14T17:49:36+00:00",
    "updated_at": "2022-10-14T17:49:36+00:00",
    "name": "DR. STEVE BRULE",
    "company": null,
    "street1": "179 N HARBOR DR",
    "street2": null,
    "city": "REDONDO BEACH",
    "state": "CA",
    "zip": "90277-2506",
    "country": "US",
    "phone": "8573875756",
    "email": "DR_STEVE_BRULE@GMAIL.COM",
    "mode": "test",
    "carrier_facility": null,
    "residential": false,
    "federal_tax_id": null,
    "state_tax_id": null,
    "verifications": {
      "zip4": {
        "success": true,
        "errors": [],
        "details": null
      },
      "delivery": {
        "success": true,
        "errors": [],
        "details": {
          "latitude": 33.8436,
          "longitude": -118.39177,
          "time_zone": "America/Los_Angeles"
        }
      }
    }
  },
  "from_address": {
    "id": "adr_91a4575b4be811edab5aac1f6bc7b362",
    "object": "Address",
    "created_at": "2022-10-14T17:49:36+00:00",
    "updated_at": "2022-10-14T17:49:36+00:00",
    "name": "EASYPOST",
    "company": null,
    "street1": "417 MONTGOMERY ST # 5",
    "street2": null,
    "city": "SAN FRANCISCO",
    "state": "CA",
    "zip": "94104-1129",
    "country": "US",
    "phone": "4153334445",
    "email": "SUPPORT@EASYPOST.COM",
    "mode": "test",
    "carrier_facility": null,
    "residential": false,
    "federal_tax_id": null,
    "state_tax_id": null,
    "verifications": {
      "zip4": {
        "success": true,
        "errors": [
          {
            "code": "E.SECONDARY_INFORMATION.INVALID",
            "field": "street2",
            "message": "Invalid secondary information(Apt/Suite#)",
            "suggestion": null
          }
        ],
        "details": null
      },
      "delivery": {
        "success": true,
        "errors": [
          {
            "code": "E.SECONDARY_INFORMATION.INVALID",
            "field": "street2",
            "message": "Invalid secondary information(Apt/Suite#)",
            "suggestion": null
          }
        ],
        "details": {
          "latitude": 37.79342,
          "longitude": -122.40288,
          "time_zone": "America/Los_Angeles"
        }
      }
    }
  },
  "shipment_id": null,
  "tracker": null,
  "tracking_code": "9400110898825022579493",
  "fee": {
    "object": "Fee",
    "type": "InsuranceFee",
    "amount": "0.50000",
    "charged": true,
    "refunded": false
  },
  "messages": [],
  "created_at": "2022-10-14T17:49:36Z",
  "updated_at": "2022-10-14T17:49:36Z"
}

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.

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	string	The associated Insurance amount
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	integer	The USPS zone of the shipment, if purchased with USPS
status	string	The current status of the shipment, possible values are "unknown", "pre_transit", "in_transit", "out_for_delivery", "delivered", "available_for_pickup", "return_to_sender", "failure", "cancelled" or "error"
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 status of the associated BatchShipment
batch_message	string	The current message of the associated BatchShipment
created_at	datetime
updated_at	datetime

Form Object

attribute	type	specification
id	string	Unique, begins with "form_"
object	string	"Form"
mode	string	"test" or "production"
form_type	string	The type of form that we returned, can be one of "high_value_report", "commercial_invoice", "cod_return_label", "order_summary", "cn22"
form_url	string	The address we return the form back at
submitted_electronically	boolean	If we have submitted the form to the carrier on behalf of the customer
created_at	datetime
updated_at	datetime

PostageLabel Object

attribute	type	specification
id	string	Unique, begins with "pl_"
object	string	"PostageLabel"
label_date	datetime	The date that appears on the postage label
label_epl2_url	string	The URL of the EPL2 label file
label_file_type	string	File type of the label
label_pdf_url	string	The URL of the PDF label file
label_resolution	integer	The resolution of the label
label_size	string	The size of the label
label_type	string	The type of the label
label_url	string	The URL of the label file
label_zpl_url	string	The URL of the ZPL label file
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. CustomInfo is required to rate an international Shipment, this includes when the destination is a US Territory. The associated Tracker, Fee, 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. If the CarrierAccount IDs provided are invalid or disabled, the shipment creation call will result in an error.

Request Parameters

param	example	info
reference	"my-reference"	An optional field that may be used in place of id in other API endpoints
to_address	<Address>	Can be specified by ID or attributes to create a new one, and be verified inline. See Create and Verify Address
from_address	<Address>	Can be specified by ID or attributes to create a new one, and be verified inline. See Create and Verify Address
parcel	<Parcel>	The dimensions and weight of the package
carrier_accounts	["ca_...", ...]	List of carrier accounts

Example

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Newtonsoft.Json;
using EasyPost;
using EasyPost.Models.API;
using EasyPost.Parameters;

namespace EasyPostExamples
{
    public class Examples
    {
        public static async Task Main()
        {
            string apiKey = Environment.GetEnvironmentVariable("EASYPOST_API_KEY")!;

            var client = new EasyPost.Client(apiKey);

            // Create a shipment using all data in one API call

            Parameters.Shipment.Create parameters = new()
            {
                ToAddress = new Parameters.Address.Create
                {
                    Name = "Dr. Steve Brule",
                    Street1 = "417 Montgomery Street",
                    Street2 = "5th Floor",
                    City = "San Francisco",
                    State = "CA",
                    Country = "US",
                    Zip = "94104"
                },
                FromAddress = new Parameters.Address.Create
                {
                    Company = "EasyPost",
                    Street1 = "417 Montgomery Street",
                    Street2 = "Floor 5",
                    City = "San Francisco",
                    State = "CA",
                    Country = "US",
                    Zip = "94104"
                },
                Parcel = new Parameters.Parcel.Create
                {
                    Length = 8,
                    Width = 6,
                    Height = 5,
                    Weight = 10
                },
                CustomsInfo = new Parameters.CustomsInfo.Create
                {
                    ...
                }
            };

            Shipment shipment = await client.Shipment.Create(parameters);

            Console.WriteLine(JsonConvert.SerializeObject(shipment, Formatting.Indented));

            // Create a shipment using existing addresses, parcel, and customs info

            Address toAddress = await client.Address.Retrieve("adr_...");
            Address fromAddress = await client.Address.Retrieve("adr_...");
            Parcel parcel = await client.Parcel.Retrieve("prcl_...");
            CustomsInfo customsInfo = await client.CustomsInfo.Retrieve("cstinfo_...");

            parameters = new()
            {
                ToAddress = toAddress,
                FromAddress = fromAddress,
                Parcel = parcel,
                CustomsInfo = customsInfo
            };

            shipment = await client.Shipment.Create(parameters);

            Console.WriteLine(JsonConvert.SerializeObject(shipmentWithIds, Formatting.Indented));
        }
    }
}

{
  "created_at": "2023-07-10T17:30:30Z",
  "is_return": false,
  "messages": [],
  "mode": "test",
  "options": {
    "currency": "USD",
    "payment": {
      "type": "SENDER"
    },
    "date_advance": 0
  },
  "reference": null,
  "status": "unknown",
  "tracking_code": null,
  "updated_at": "2023-07-10T17:30:30Z",
  "batch_id": null,
  "batch_status": null,
  "batch_message": null,
  "customs_info": {
    "id": "cstinfo_00b8fbbef7364b709141adfaab1a12a3",
    "object": "CustomsInfo",
    "created_at": "2023-07-10T17:30:30Z",
    "updated_at": "2023-07-10T17:30:30Z",
    "contents_explanation": "",
    "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",
    "mode": "test",
    "declaration": null,
    "customs_items": [
      {
        "id": "cstitem_a4d546e735c54fae9fd3c22b135a231d",
        "object": "CustomsItem",
        "created_at": "2023-07-10T17:30:30Z",
        "updated_at": "2023-07-10T17:30:30Z",
        "description": "T-shirt",
        "hs_tariff_number": "123456",
        "origin_country": "US",
        "quantity": 1,
        "value": "10.0",
        "weight": 5.0,
        "code": "123",
        "mode": "test",
        "manufacturer": null,
        "currency": null,
        "eccn": null,
        "printed_commodity_identifier": null
      }
    ]
  },
  "from_address": {
    "id": "adr_775211ea1f4711ee991cac1f6bc539aa",
    "object": "Address",
    "created_at": "2023-07-10T17:30:30+00:00",
    "updated_at": "2023-07-10T17:30:30+00:00",
    "name": "EasyPost",
    "company": null,
    "street1": "417 Montgomery Street",
    "street2": "5th Floor",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94104",
    "country": "US",
    "phone": "4153334445",
    "email": "support@easypost.com",
    "mode": "test",
    "carrier_facility": null,
    "residential": null,
    "federal_tax_id": null,
    "state_tax_id": null,
    "verifications": {}
  },
  "insurance": null,
  "order_id": null,
  "parcel": {
    "id": "prcl_299db961ed944c2bbab8f1a6c9223611",
    "object": "Parcel",
    "created_at": "2023-07-10T17:30:30Z",
    "updated_at": "2023-07-10T17:30:30Z",
    "length": 20.2,
    "width": 10.9,
    "height": 5.0,
    "predefined_package": null,
    "weight": 65.9,
    "mode": "test"
  },
  "postage_label": null,
  "rates": [
    {
      "id": "rate_d13862f2010b455f8c8335c515da71ba",
      "object": "Rate",
      "created_at": "2023-07-10T17:30:30Z",
      "updated_at": "2023-07-10T17:30:30Z",
      "mode": "test",
      "service": "GroundAdvantage",
      "carrier": "USPS",
      "rate": "8.92",
      "currency": "USD",
      "retail_rate": "8.92",
      "retail_currency": "USD",
      "list_rate": "8.92",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": null,
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "est_delivery_days": null,
      "shipment_id": "shp_8a97fc2dc4264da78361fbe30edb3b08",
      "carrier_account_id": "ca_b25657e9896e4d63ac8151ac346ac41e"
    },
    {
      "id": "rate_ccdf9a0705ce44c6a5e449a62f5d7c13",
      "object": "Rate",
      "created_at": "2023-07-10T17:30:30Z",
      "updated_at": "2023-07-10T17:30:30Z",
      "mode": "test",
      "service": "First",
      "carrier": "USPS",
      "rate": "8.92",
      "currency": "USD",
      "retail_rate": "8.92",
      "retail_currency": "USD",
      "list_rate": "8.92",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": 3,
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "est_delivery_days": 3,
      "shipment_id": "shp_8a97fc2dc4264da78361fbe30edb3b08",
      "carrier_account_id": "ca_b25657e9896e4d63ac8151ac346ac41e"
    },
    {
      "id": "rate_1d1657be86214c5fba29a70916bc92dc",
      "object": "Rate",
      "created_at": "2023-07-10T17:30:30Z",
      "updated_at": "2023-07-10T17:30:30Z",
      "mode": "test",
      "service": "Express",
      "carrier": "USPS",
      "rate": "46.85",
      "currency": "USD",
      "retail_rate": "54.20",
      "retail_currency": "USD",
      "list_rate": "46.85",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": null,
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "est_delivery_days": null,
      "shipment_id": "shp_8a97fc2dc4264da78361fbe30edb3b08",
      "carrier_account_id": "ca_b25657e9896e4d63ac8151ac346ac41e"
    },
    {
      "id": "rate_3871229b5b064f36a10452eaa442df3d",
      "object": "Rate",
      "created_at": "2023-07-10T17:30:30Z",
      "updated_at": "2023-07-10T17:30:30Z",
      "mode": "test",
      "service": "Priority",
      "carrier": "USPS",
      "rate": "7.47",
      "currency": "USD",
      "retail_rate": "14.05",
      "retail_currency": "USD",
      "list_rate": "10.27",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": 2,
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "est_delivery_days": 2,
      "shipment_id": "shp_8a97fc2dc4264da78361fbe30edb3b08",
      "carrier_account_id": "ca_b25657e9896e4d63ac8151ac346ac41e"
    }
  ],
  "refund_status": null,
  "scan_form": null,
  "selected_rate": null,
  "tracker": null,
  "to_address": {
    "id": "adr_774f94ae1f4711ee9919ac1f6bc539aa",
    "object": "Address",
    "created_at": "2023-07-10T17:30:29+00:00",
    "updated_at": "2023-07-10T17:30:29+00:00",
    "name": "Dr. Steve Brule",
    "company": null,
    "street1": "179 N Harbor Dr",
    "street2": null,
    "city": "Redondo Beach",
    "state": "CA",
    "zip": "90277",
    "country": "US",
    "phone": "8573875756",
    "email": "dr_steve_brule@gmail.com",
    "mode": "test",
    "carrier_facility": null,
    "residential": null,
    "federal_tax_id": null,
    "state_tax_id": null,
    "verifications": {}
  },
  "usps_zone": 4,
  "return_address": {
    "id": "adr_775211ea1f4711ee991cac1f6bc539aa",
    "object": "Address",
    "created_at": "2023-07-10T17:30:30+00:00",
    "updated_at": "2023-07-10T17:30:30+00:00",
    "name": "EasyPost",
    "company": null,
    "street1": "417 Montgomery Street",
    "street2": "5th Floor",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94104",
    "country": "US",
    "phone": "4153334445",
    "email": "support@easypost.com",
    "mode": "test",
    "carrier_facility": null,
    "residential": null,
    "federal_tax_id": null,
    "state_tax_id": null,
    "verifications": {}
  },
  "buyer_address": {
    "id": "adr_774f94ae1f4711ee9919ac1f6bc539aa",
    "object": "Address",
    "created_at": "2023-07-10T17:30:29+00:00",
    "updated_at": "2023-07-10T17:30:29+00:00",
    "name": "Dr. Steve Brule",
    "company": null,
    "street1": "179 N Harbor Dr",
    "street2": null,
    "city": "Redondo Beach",
    "state": "CA",
    "zip": "90277",
    "country": "US",
    "phone": "8573875756",
    "email": "dr_steve_brule@gmail.com",
    "mode": "test",
    "carrier_facility": null,
    "residential": null,
    "federal_tax_id": null,
    "state_tax_id": null,
    "verifications": {}
  },
  "forms": [],
  "fees": [],
  "id": "shp_8a97fc2dc4264da78361fbe30edb3b08",
  "object": "Shipment"
}

GET/shipments

Retrieve a list of Shipments

The Shipment List is a paginated list of all Shipment objects associated with the given API Key. See the Pagination section of our docs for more details on retrieving all records when multiple pages are available.

Request Parameters

param	example	info
before_id	shp_...	Optional pagination parameter. Only shipments created before the given ID will be included. May not be used with after_id
after_id	shp_...	Optional pagination parameter. Only shipments created after the given ID will be included. May not be used with before_id
start_datetime	2016-01-02T00:00:00Z	Only return Shipments 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 Shipments created before this timestamp. Defaults to end of the current day, or 1 month after a passed start_datetime
page_size	20	The number of Shipments to return on each page. The maximum value is 100
purchased	true	Only include Shipments that have been purchased. Default is `true`
include_children	false	Also include Shipments created by Child Users. Defaults to `false`

Example

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Newtonsoft.Json;
using EasyPost;
using EasyPost.Models.API;
using EasyPost.Parameters;

namespace EasyPostExamples
{
    public class Examples
    {
        public static async Task Main()
        {
            string apiKey = Environment.GetEnvironmentVariable("EASYPOST_API_KEY")!;

            var client = new EasyPost.Client(apiKey);

            Parameters.Shipment.All parameters = new()
            {
                PageSize = 5
            };

            ShipmentCollection shipmentCollection = await client.Shipment.All(parameters);

            Console.WriteLine(JsonConvert.SerializeObject(shipmentCollection, Formatting.Indented));
        }
    }
}

{
  "shipments": [
    {
      "created_at": "2023-07-10T17:30:14Z",
      "is_return": false,
      "messages": [],
      "mode": "test",
      "options": {
        "currency": "USD",
        "payment": {
          "type": "SENDER"
        },
        "date_advance": 0
      },
      "reference": null,
      "status": "unknown",
      "tracking_code": "9400100105440232838888",
      "updated_at": "2023-07-10T17:30:16Z",
      "batch_id": null,
      "batch_status": null,
      "batch_message": null,
      "customs_info": {
        "id": "cstinfo_f85189b578ec4706ac387b76cec7ff01",
        "object": "CustomsInfo",
        "created_at": "2022-10-17T17:17:38Z",
        "updated_at": "2022-10-17T17:17:38Z",
        "contents_explanation": "",
        "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",
        "mode": "test",
        "declaration": null,
        "customs_items": [
          {
            "id": "cstitem_fa0aa9aa3a8f41639295c10aa7469480",
            "object": "CustomsItem",
            "created_at": "2022-10-17T17:17:38Z",
            "updated_at": "2022-10-17T17:17:38Z",
            "description": "T-shirt",
            "hs_tariff_number": "123456",
            "origin_country": "US",
            "quantity": 1,
            "value": "10.0",
            "weight": 5.0,
            "code": "123",
            "mode": "test",
            "manufacturer": null,
            "currency": null,
            "eccn": null,
            "printed_commodity_identifier": null
          }
        ]
      },
      "from_address": {
        "id": "adr_6e0ac14a1f4711eeacd5ac1f6bc539ae",
        "object": "Address",
        "created_at": "2023-07-10T17:30:14+00:00",
        "updated_at": "2023-07-10T17:30:14+00:00",
        "name": "EasyPost",
        "company": null,
        "street1": "417 Montgomery Street",
        "street2": "5th Floor",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94104",
        "country": "US",
        "phone": "4153334445",
        "email": "support@easypost.com",
        "mode": "test",
        "carrier_facility": null,
        "residential": null,
        "federal_tax_id": null,
        "state_tax_id": null,
        "verifications": {}
      },
      "insurance": null,
      "order_id": "order_2666c9282ad54765b74b9be1c0cccf09",
      "parcel": {
        "id": "prcl_2498d756b1c740b484f5665e5fdd697f",
        "object": "Parcel",
        "created_at": "2023-07-10T17:30:14Z",
        "updated_at": "2023-07-10T17:30:14Z",
        "length": null,
        "width": null,
        "height": null,
        "predefined_package": null,
        "weight": 10.2,
        "mode": "test"
      },
      "postage_label": {
        "object": "PostageLabel",
        "id": "pl_ce7b1a9249794cd697c87395d660d8f6",
        "created_at": "2023-07-10T17:30:15Z",
        "updated_at": "2023-07-10T17:30:16Z",
        "date_advance": 0,
        "integrated_form": "none",
        "label_date": "2023-07-10T17:30:15Z",
        "label_resolution": 300,
        "label_size": "4x6",
        "label_type": "default",
        "label_file_type": "image/png",
        "label_url": "https://easypost-files.s3.us-west-2.amazonaws.com/files/postage_label/20230710/e657608f44b6ec482c86742b7b8ea5d74d.png",
        "label_pdf_url": null,
        "label_zpl_url": null,
        "label_epl2_url": null,
        "label_file": null
      },
      "rates": [
        {
          "id": "rate_d669ba48a22b4f7f9a07939bf509de2a",
          "object": "Rate",
          "created_at": "2023-07-10T17:30:15Z",
          "updated_at": "2023-07-10T17:30:15Z",
          "mode": "test",
          "service": "Express",
          "carrier": "USPS",
          "rate": "31.25",
          "currency": "USD",
          "retail_rate": "35.80",
          "retail_currency": "USD",
          "list_rate": "31.25",
          "list_currency": "USD",
          "billing_type": "easypost",
          "delivery_days": null,
          "delivery_date": null,
          "delivery_date_guaranteed": false,
          "est_delivery_days": null,
          "shipment_id": "shp_06a2ad37dc1c425c88c593f3e9cf5ea4",
          "carrier_account_id": "ca_b25657e9896e4d63ac8151ac346ac41e"
        },
        {
          "id": "rate_ee0ba720bd6a4338b2945db6e450baba",
          "object": "Rate",
          "created_at": "2023-07-10T17:30:15Z",
          "updated_at": "2023-07-10T17:30:15Z",
          "mode": "test",
          "service": "Priority",
          "carrier": "USPS",
          "rate": "7.15",
          "currency": "USD",
          "retail_rate": "10.20",
          "retail_currency": "USD",
          "list_rate": "8.24",
          "list_currency": "USD",
          "billing_type": "easypost",
          "delivery_days": 2,
          "delivery_date": null,
          "delivery_date_guaranteed": false,
          "est_delivery_days": 2,
          "shipment_id": "shp_06a2ad37dc1c425c88c593f3e9cf5ea4",
          "carrier_account_id": "ca_b25657e9896e4d63ac8151ac346ac41e"
        },
        {
          "id": "rate_fd2144b885dd4725bfdf4ece351e9231",
          "object": "Rate",
          "created_at": "2023-07-10T17:30:15Z",
          "updated_at": "2023-07-10T17:30:15Z",
          "mode": "test",
          "service": "GroundAdvantage",
          "carrier": "USPS",
          "rate": "4.81",
          "currency": "USD",
          "retail_rate": "4.81",
          "retail_currency": "USD",
          "list_rate": "4.81",
          "list_currency": "USD",
          "billing_type": "easypost",
          "delivery_days": null,
          "delivery_date": null,
          "delivery_date_guaranteed": false,
          "est_delivery_days": null,
          "shipment_id": "shp_06a2ad37dc1c425c88c593f3e9cf5ea4",
          "carrier_account_id": "ca_b25657e9896e4d63ac8151ac346ac41e"
        },
        {
          "id": "rate_5dff1ed420df4a58833d9b47563565f6",
          "object": "Rate",
          "created_at": "2023-07-10T17:30:15Z",
          "updated_at": "2023-07-10T17:30:15Z",
          "mode": "test",
          "service": "First",
          "carrier": "USPS",
          "rate": "4.81",
          "currency": "USD",
          "retail_rate": "4.81",
          "retail_currency": "USD",
          "list_rate": "4.81",
          "list_currency": "USD",
          "billing_type": "easypost",
          "delivery_days": 3,
          "delivery_date": null,
          "delivery_date_guaranteed": false,
          "est_delivery_days": 3,
          "shipment_id": "shp_06a2ad37dc1c425c88c593f3e9cf5ea4",
          "carrier_account_id": "ca_b25657e9896e4d63ac8151ac346ac41e"
        }
      ],
      "refund_status": null,
      "scan_form": {
        "id": "sf_3684195c590740a88bc2c2cf5f25acb1",
        "object": "ScanForm",
        "created_at": "2022-10-17T17:17:39Z",
        "updated_at": "2022-10-17T17:17:40Z",
        "tracking_codes": ["9405500106068143632993"],
        "address": {
          "id": "adr_99962d534e3f11ed846dac1f6b0a0d1e",
          "object": "Address",
          "created_at": "2022-10-17T17:17:38+00:00",
          "updated_at": "2022-10-17T17:17:38+00:00",
          "name": "EasyPost",
          "company": null,
          "street1": "417 Montgomery Street",
          "street2": "5th Floor",
          "city": "San Francisco",
          "state": "CA",
          "zip": "94104",
          "country": "US",
          "phone": "4153334445",
          "email": "support@easypost.com",
          "mode": "test",
          "carrier_facility": null,
          "residential": null,
          "federal_tax_id": null,
          "state_tax_id": null,
          "verifications": {}
        },
        "status": "created",
        "message": null,
        "form_url": "https://easypost-files.s3.us-west-2.amazonaws.com/files/scan_form/20221017/58d6eef422424d02bd4105029666d614.pdf",
        "form_file_type": null,
        "batch_id": "batch_879633ae98a847409f0ca5b22c9872f4",
        "confirmation": null
      },
      "selected_rate": {
        "id": "rate_5dff1ed420df4a58833d9b47563565f6",
        "object": "Rate",
        "created_at": "2023-07-10T17:30:15Z",
        "updated_at": "2023-07-10T17:30:15Z",
        "mode": "test",
        "service": "First",
        "carrier": "USPS",
        "rate": "4.81",
        "currency": "USD",
        "retail_rate": "4.81",
        "retail_currency": "USD",
        "list_rate": "4.81",
        "list_currency": "USD",
        "billing_type": "easypost",
        "delivery_days": 3,
        "delivery_date": null,
        "delivery_date_guaranteed": false,
        "est_delivery_days": 3,
        "shipment_id": "shp_06a2ad37dc1c425c88c593f3e9cf5ea4",
        "carrier_account_id": "ca_b25657e9896e4d63ac8151ac346ac41e"
      },
      "tracker": {
        "id": "trk_1c56526a89e04c4c80013fd763f91228",
        "object": "Tracker",
        "mode": "test",
        "tracking_code": "9400100105440232838888",
        "status": "pre_transit",
        "status_detail": "status_update",
        "created_at": "2023-07-10T17:30:16Z",
        "updated_at": "2023-07-10T17:30:16Z",
        "signed_by": null,
        "weight": null,
        "est_delivery_date": "2023-07-10T17:30:16Z",
        "shipment_id": "shp_06a2ad37dc1c425c88c593f3e9cf5ea4",
        "carrier": "USPS",
        "tracking_details": [
          {
            "object": "TrackingDetail",
            "message": "Pre-Shipment Info Sent to USPS",
            "description": null,
            "status": "pre_transit",
            "status_detail": "status_update",
            "datetime": "2023-06-10T17:30:16Z",
            "source": "USPS",
            "carrier_code": null,
            "tracking_location": {
              "object": "TrackingLocation",
              "city": null,
              "state": null,
              "country": null,
              "zip": null
            }
          },
          {
            "object": "TrackingDetail",
            "message": "Shipping Label Created",
            "description": null,
            "status": "pre_transit",
            "status_detail": "status_update",
            "datetime": "2023-06-11T06:07:16Z",
            "source": "USPS",
            "carrier_code": null,
            "tracking_location": {
              "object": "TrackingLocation",
              "city": "HOUSTON",
              "state": "TX",
              "country": null,
              "zip": "77063"
            }
          }
        ],
        "fees": [],
        "carrier_detail": {
          "object": "CarrierDetail",
          "service": "First-Class Package Service",
          "container_type": null,
          "est_delivery_date_local": null,
          "est_delivery_time_local": null,
          "origin_location": "HOUSTON TX, 77001",
          "origin_tracking_location": {
            "object": "TrackingLocation",
            "city": "HOUSTON",
            "state": "TX",
            "country": null,
            "zip": "77063"
          },
          "destination_location": "CHARLESTON SC, 29401",
          "destination_tracking_location": null,
          "guaranteed_delivery_date": null,
          "alternate_identifier": null,
          "initial_delivery_attempt": null
        },
        "public_url": "https://track.easypost.com/djE6dHJrXzFjNTY1MjZhODllMDRjNGM4MDAxM2ZkNzYzZjkxMjI4"
      },
      "to_address": {
        "id": "adr_6e09528d1f4711ee9deaac1f6bc53342",
        "object": "Address",
        "created_at": "2023-07-10T17:30:14+00:00",
        "updated_at": "2023-07-10T17:30:15+00:00",
        "name": "DR. STEVE BRULE",
        "company": null,
        "street1": "179 N HARBOR DR",
        "street2": null,
        "city": "REDONDO BEACH",
        "state": "CA",
        "zip": "90277-2506",
        "country": "US",
        "phone": "8573875756",
        "email": "DR_STEVE_BRULE@GMAIL.COM",
        "mode": "test",
        "carrier_facility": null,
        "residential": false,
        "federal_tax_id": null,
        "state_tax_id": null,
        "verifications": {
          "zip4": {
            "success": true,
            "errors": [],
            "details": null
          },
          "delivery": {
            "success": true,
            "errors": [],
            "details": {
              "latitude": 33.8436,
              "longitude": -118.39177,
              "time_zone": "America/Los_Angeles"
            }
          }
        }
      },
      "usps_zone": 4,
      "return_address": {
        "id": "adr_6e0ac14a1f4711eeacd5ac1f6bc539ae",
        "object": "Address",
        "created_at": "2023-07-10T17:30:14+00:00",
        "updated_at": "2023-07-10T17:30:14+00:00",
        "name": "EasyPost",
        "company": null,
        "street1": "417 Montgomery Street",
        "street2": "5th Floor",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94104",
        "country": "US",
        "phone": "4153334445",
        "email": "support@easypost.com",
        "mode": "test",
        "carrier_facility": null,
        "residential": null,
        "federal_tax_id": null,
        "state_tax_id": null,
        "verifications": {}
      },
      "buyer_address": {
        "id": "adr_6e09528d1f4711ee9deaac1f6bc53342",
        "object": "Address",
        "created_at": "2023-07-10T17:30:14+00:00",
        "updated_at": "2023-07-10T17:30:15+00:00",
        "name": "DR. STEVE BRULE",
        "company": null,
        "street1": "179 N HARBOR DR",
        "street2": null,
        "city": "REDONDO BEACH",
        "state": "CA",
        "zip": "90277-2506",
        "country": "US",
        "phone": "8573875756",
        "email": "DR_STEVE_BRULE@GMAIL.COM",
        "mode": "test",
        "carrier_facility": null,
        "residential": false,
        "federal_tax_id": null,
        "state_tax_id": null,
        "verifications": {
          "zip4": {
            "success": true,
            "errors": [],
            "details": null
          },
          "delivery": {
            "success": true,
            "errors": [],
            "details": {
              "latitude": 33.8436,
              "longitude": -118.39177,
              "time_zone": "America/Los_Angeles"
            }
          }
        }
      },
      "forms": [],
      "fees": [
        {
          "object": "Fee",
          "type": "LabelFee",
          "amount": "0.00000",
          "charged": true,
          "refunded": false
        },
        {
          "object": "Fee",
          "type": "PostageFee",
          "amount": "4.81000",
          "charged": true,
          "refunded": false
        }
      ],
      "id": "shp_06a2ad37dc1c425c88c593f3e9cf5ea4",
      "object": "Shipment"
    }
  ],
  "has_more": true
}

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.

Example

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Newtonsoft.Json;
using EasyPost;
using EasyPost.Models.API;

namespace EasyPostExamples
{
    public class Examples
    {
        public static async Task Main()
        {
            string apiKey = Environment.GetEnvironmentVariable("EASYPOST_API_KEY")!;

            var client = new EasyPost.Client(apiKey);

            Shipment shipment = await client.Shipment.Retrieve("shp_...");

            Console.WriteLine(JsonConvert.SerializeObject(shipment, Formatting.Indented));
        }
    }
}

{
  "created_at": "2023-07-10T17:30:31Z",
  "is_return": false,
  "messages": [],
  "mode": "test",
  "options": {
    "currency": "USD",
    "payment": {
      "type": "SENDER"
    },
    "date_advance": 0
  },
  "reference": null,
  "status": "unknown",
  "tracking_code": null,
  "updated_at": "2023-07-10T17:30:31Z",
  "batch_id": null,
  "batch_status": null,
  "batch_message": null,
  "customs_info": {
    "id": "cstinfo_4afc2245f2d5457c85d01d25f7c6af16",
    "object": "CustomsInfo",
    "created_at": "2023-07-10T17:30:31Z",
    "updated_at": "2023-07-10T17:30:31Z",
    "contents_explanation": "",
    "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",
    "mode": "test",
    "declaration": null,
    "customs_items": [
      {
        "id": "cstitem_c989133bfaa54249b7c811162e737878",
        "object": "CustomsItem",
        "created_at": "2023-07-10T17:30:31Z",
        "updated_at": "2023-07-10T17:30:31Z",
        "description": "T-shirt",
        "hs_tariff_number": "123456",
        "origin_country": "US",
        "quantity": 1,
        "value": "10.0",
        "weight": 5.0,
        "code": "123",
        "mode": "test",
        "manufacturer": null,
        "currency": null,
        "eccn": null,
        "printed_commodity_identifier": null
      }
    ]
  },
  "from_address": {
    "id": "adr_77eb19ac1f4711eea161ac1f6bc53342",
    "object": "Address",
    "created_at": "2023-07-10T17:30:31+00:00",
    "updated_at": "2023-07-10T17:30:31+00:00",
    "name": "EasyPost",
    "company": null,
    "street1": "417 Montgomery Street",
    "street2": "5th Floor",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94104",
    "country": "US",
    "phone": "4153334445",
    "email": "support@easypost.com",
    "mode": "test",
    "carrier_facility": null,
    "residential": null,
    "federal_tax_id": null,
    "state_tax_id": null,
    "verifications": {}
  },
  "insurance": null,
  "order_id": null,
  "parcel": {
    "id": "prcl_58211c2b2ec34ccb963f563af84465ef",
    "object": "Parcel",
    "created_at": "2023-07-10T17:30:31Z",
    "updated_at": "2023-07-10T17:30:31Z",
    "length": 20.2,
    "width": 10.9,
    "height": 5.0,
    "predefined_package": null,
    "weight": 65.9,
    "mode": "test"
  },
  "postage_label": null,
  "rates": [
    {
      "id": "rate_edd39ae11117495f9337cc6082b92d6b",
      "object": "Rate",
      "created_at": "2023-07-10T17:30:31Z",
      "updated_at": "2023-07-10T17:30:31Z",
      "mode": "test",
      "service": "Express",
      "carrier": "USPS",
      "rate": "46.85",
      "currency": "USD",
      "retail_rate": "54.20",
      "retail_currency": "USD",
      "list_rate": "46.85",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": null,
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "est_delivery_days": null,
      "shipment_id": "shp_f18f9517691a4a5bba27db1c477bc33a",
      "carrier_account_id": "ca_b25657e9896e4d63ac8151ac346ac41e"
    },
    {
      "id": "rate_d6fc4aacf0694055aa8fc660d32237bc",
      "object": "Rate",
      "created_at": "2023-07-10T17:30:31Z",
      "updated_at": "2023-07-10T17:30:31Z",
      "mode": "test",
      "service": "Priority",
      "carrier": "USPS",
      "rate": "7.47",
      "currency": "USD",
      "retail_rate": "14.05",
      "retail_currency": "USD",
      "list_rate": "10.27",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": 2,
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "est_delivery_days": 2,
      "shipment_id": "shp_f18f9517691a4a5bba27db1c477bc33a",
      "carrier_account_id": "ca_b25657e9896e4d63ac8151ac346ac41e"
    },
    {
      "id": "rate_708f651251a14e82bc6c4d3d2f97b442",
      "object": "Rate",
      "created_at": "2023-07-10T17:30:31Z",
      "updated_at": "2023-07-10T17:30:31Z",
      "mode": "test",
      "service": "GroundAdvantage",
      "carrier": "USPS",
      "rate": "8.92",
      "currency": "USD",
      "retail_rate": "8.92",
      "retail_currency": "USD",
      "list_rate": "8.92",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": null,
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "est_delivery_days": null,
      "shipment_id": "shp_f18f9517691a4a5bba27db1c477bc33a",
      "carrier_account_id": "ca_b25657e9896e4d63ac8151ac346ac41e"
    },
    {
      "id": "rate_56268a3e3e4349a1bb8c3d371c7702ba",
      "object": "Rate",
      "created_at": "2023-07-10T17:30:31Z",
      "updated_at": "2023-07-10T17:30:31Z",
      "mode": "test",
      "service": "First",
      "carrier": "USPS",
      "rate": "8.92",
      "currency": "USD",
      "retail_rate": "8.92",
      "retail_currency": "USD",
      "list_rate": "8.92",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": 3,
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "est_delivery_days": 3,
      "shipment_id": "shp_f18f9517691a4a5bba27db1c477bc33a",
      "carrier_account_id": "ca_b25657e9896e4d63ac8151ac346ac41e"
    }
  ],
  "refund_status": null,
  "scan_form": null,
  "selected_rate": null,
  "tracker": null,
  "to_address": {
    "id": "adr_77e8ae4e1f4711ee997aac1f6bc539aa",
    "object": "Address",
    "created_at": "2023-07-10T17:30:30+00:00",
    "updated_at": "2023-07-10T17:30:30+00:00",
    "name": "Dr. Steve Brule",
    "company": null,
    "street1": "179 N Harbor Dr",
    "street2": null,
    "city": "Redondo Beach",
    "state": "CA",
    "zip": "90277",
    "country": "US",
    "phone": "8573875756",
    "email": "dr_steve_brule@gmail.com",
    "mode": "test",
    "carrier_facility": null,
    "residential": null,
    "federal_tax_id": null,
    "state_tax_id": null,
    "verifications": {}
  },
  "usps_zone": 4,
  "return_address": {
    "id": "adr_77eb19ac1f4711eea161ac1f6bc53342",
    "object": "Address",
    "created_at": "2023-07-10T17:30:31+00:00",
    "updated_at": "2023-07-10T17:30:31+00:00",
    "name": "EasyPost",
    "company": null,
    "street1": "417 Montgomery Street",
    "street2": "5th Floor",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94104",
    "country": "US",
    "phone": "4153334445",
    "email": "support@easypost.com",
    "mode": "test",
    "carrier_facility": null,
    "residential": null,
    "federal_tax_id": null,
    "state_tax_id": null,
    "verifications": {}
  },
  "buyer_address": {
    "id": "adr_77e8ae4e1f4711ee997aac1f6bc539aa",
    "object": "Address",
    "created_at": "2023-07-10T17:30:30+00:00",
    "updated_at": "2023-07-10T17:30:30+00:00",
    "name": "Dr. Steve Brule",
    "company": null,
    "street1": "179 N Harbor Dr",
    "street2": null,
    "city": "Redondo Beach",
    "state": "CA",
    "zip": "90277",
    "country": "US",
    "phone": "8573875756",
    "email": "dr_steve_brule@gmail.com",
    "mode": "test",
    "carrier_facility": null,
    "residential": null,
    "federal_tax_id": null,
    "state_tax_id": null,
    "verifications": {}
  },
  "forms": [],
  "fees": [],
  "id": "shp_f18f9517691a4a5bba27db1c477bc33a",
  "object": "Shipment"
}

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.

Request Parameters

param	example
rate	<Rate>
insurance	"100.00"

Example

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Newtonsoft.Json;
using EasyPost;
using EasyPost.Models.API;
using EasyPost.Parameters;

namespace EasyPostExamples
{
    public class Examples
    {
        public static async Task Main()
        {
            string apiKey = Environment.GetEnvironmentVariable("EASYPOST_API_KEY")!;

            var client = new EasyPost.Client(apiKey);

            Shipment shipment = await client.Shipment.Retrieve("shp_...");

            Rate rate = shipment.LowestRate();

            Parameters.Shipment.Buy parameters = new(rate);

            shipment = await client.Shipment.Buy(shipment.Id, parameters);

            Console.WriteLine(JsonConvert.SerializeObject(shipment, Formatting.Indented));
        }
    }
}

{
  "created_at": "2023-07-10T17:30:32Z",
  "is_return": false,
  "messages": [],
  "mode": "test",
  "options": {
    "currency": "USD",
    "payment": {
      "type": "SENDER"
    },
    "date_advance": 0
  },
  "reference": null,
  "status": "unknown",
  "tracking_code": "9405500105440232839154",
  "updated_at": "2023-07-10T17:30:34Z",
  "batch_id": null,
  "batch_status": null,
  "batch_message": null,
  "customs_info": {
    "id": "cstinfo_966c3d97171348d58a521331a78e787d",
    "object": "CustomsInfo",
    "created_at": "2023-07-10T17:30:32Z",
    "updated_at": "2023-07-10T17:30:32Z",
    "contents_explanation": "",
    "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",
    "mode": "test",
    "declaration": null,
    "customs_items": [
      {
        "id": "cstitem_fc1e3c91391a4fada67cdde755cc1084",
        "object": "CustomsItem",
        "created_at": "2023-07-10T17:30:32Z",
        "updated_at": "2023-07-10T17:30:32Z",
        "description": "T-shirt",
        "hs_tariff_number": "123456",
        "origin_country": "US",
        "quantity": 1,
        "value": "10.0",
        "weight": 5.0,
        "code": "123",
        "mode": "test",
        "manufacturer": null,
        "currency": null,
        "eccn": null,
        "printed_commodity_identifier": null
      }
    ]
  },
  "from_address": {
    "id": "adr_790830351f4711ee972c3cecef1b359e",
    "object": "Address",
    "created_at": "2023-07-10T17:30:32+00:00",
    "updated_at": "2023-07-10T17:30:32+00:00",
    "name": "EasyPost",
    "company": null,
    "street1": "417 Montgomery Street",
    "street2": "5th Floor",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94104",
    "country": "US",
    "phone": "4153334445",
    "email": "support@easypost.com",
    "mode": "test",
    "carrier_facility": null,
    "residential": null,
    "federal_tax_id": null,
    "state_tax_id": null,
    "verifications": {}
  },
  "insurance": "249.99",
  "order_id": null,
  "parcel": {
    "id": "prcl_013b6187c18d44b5bfdc05e0e795f033",
    "object": "Parcel",
    "created_at": "2023-07-10T17:30:32Z",
    "updated_at": "2023-07-10T17:30:32Z",
    "length": 20.2,
    "width": 10.9,
    "height": 5.0,
    "predefined_package": null,
    "weight": 65.9,
    "mode": "test"
  },
  "postage_label": {
    "object": "PostageLabel",
    "id": "pl_ed73e71d2910440bac0eae34a6e4c9fa",
    "created_at": "2023-07-10T17:30:34Z",
    "updated_at": "2023-07-10T17:30:34Z",
    "date_advance": 0,
    "integrated_form": "none",
    "label_date": "2023-07-10T17:30:34Z",
    "label_resolution": 300,
    "label_size": "4x6",
    "label_type": "default",
    "label_file_type": "image/png",
    "label_url": "https://easypost-files.s3.us-west-2.amazonaws.com/files/postage_label/20230710/e6ad0a33bff1634f128c21d0e75e066491.png",
    "label_pdf_url": null,
    "label_zpl_url": null,
    "label_epl2_url": null,
    "label_file": null
  },
  "rates": [
    {
      "id": "rate_22ca9cdf88be4b5da8e91b051e673534",
      "object": "Rate",
      "created_at": "2023-07-10T17:30:33Z",
      "updated_at": "2023-07-10T17:30:33Z",
      "mode": "test",
      "service": "Priority",
      "carrier": "USPS",
      "rate": "7.47",
      "currency": "USD",
      "retail_rate": "14.05",
      "retail_currency": "USD",
      "list_rate": "10.27",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": 2,
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "est_delivery_days": 2,
      "shipment_id": "shp_5948db965e944950b6acc052af7f79a1",
      "carrier_account_id": "ca_b25657e9896e4d63ac8151ac346ac41e"
    },
    {
      "id": "rate_e4df015173864a1a8c4e2144e2eeb055",
      "object": "Rate",
      "created_at": "2023-07-10T17:30:33Z",
      "updated_at": "2023-07-10T17:30:33Z",
      "mode": "test",
      "service": "GroundAdvantage",
      "carrier": "USPS",
      "rate": "8.92",
      "currency": "USD",
      "retail_rate": "8.92",
      "retail_currency": "USD",
      "list_rate": "8.92",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": null,
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "est_delivery_days": null,
      "shipment_id": "shp_5948db965e944950b6acc052af7f79a1",
      "carrier_account_id": "ca_b25657e9896e4d63ac8151ac346ac41e"
    },
    {
      "id": "rate_2e03d36753184d18aa4bd1beaea4f225",
      "object": "Rate",
      "created_at": "2023-07-10T17:30:33Z",
      "updated_at": "2023-07-10T17:30:33Z",
      "mode": "test",
      "service": "First",
      "carrier": "USPS",
      "rate": "8.92",
      "currency": "USD",
      "retail_rate": "8.92",
      "retail_currency": "USD",
      "list_rate": "8.92",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": 3,
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "est_delivery_days": 3,
      "shipment_id": "shp_5948db965e944950b6acc052af7f79a1",
      "carrier_account_id": "ca_b25657e9896e4d63ac8151ac346ac41e"
    },
    {
      "id": "rate_58096b68cfdc472abc792957917ab92f",
      "object": "Rate",
      "created_at": "2023-07-10T17:30:33Z",
      "updated_at": "2023-07-10T17:30:33Z",
      "mode": "test",
      "service": "Express",
      "carrier": "USPS",
      "rate": "46.85",
      "currency": "USD",
      "retail_rate": "54.20",
      "retail_currency": "USD",
      "list_rate": "46.85",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": null,
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "est_delivery_days": null,
      "shipment_id": "shp_5948db965e944950b6acc052af7f79a1",
      "carrier_account_id": "ca_b25657e9896e4d63ac8151ac346ac41e"
    }
  ],
  "refund_status": null,
  "scan_form": null,
  "selected_rate": {
    "id": "rate_22ca9cdf88be4b5da8e91b051e673534",
    "object": "Rate",
    "created_at": "2023-07-10T17:30:34Z",
    "updated_at": "2023-07-10T17:30:34Z",
    "mode": "test",
    "service": "Priority",
    "carrier": "USPS",
    "rate": "7.47",
    "currency": "USD",
    "retail_rate": "14.05",
    "retail_currency": "USD",
    "list_rate": "10.27",
    "list_currency": "USD",
    "billing_type": "easypost",
    "delivery_days": 2,
    "delivery_date": null,
    "delivery_date_guaranteed": false,
    "est_delivery_days": 2,
    "shipment_id": "shp_5948db965e944950b6acc052af7f79a1",
    "carrier_account_id": "ca_b25657e9896e4d63ac8151ac346ac41e"
  },
  "tracker": {
    "id": "trk_618b31761819423cbd5820c11949ce41",
    "object": "Tracker",
    "mode": "test",
    "tracking_code": "9405500105440232839154",
    "status": "unknown",
    "status_detail": "unknown",
    "created_at": "2023-07-10T17:30:34Z",
    "updated_at": "2023-07-10T17:30:34Z",
    "signed_by": null,
    "weight": null,
    "est_delivery_date": null,
    "shipment_id": "shp_5948db965e944950b6acc052af7f79a1",
    "carrier": "USPS",
    "tracking_details": [],
    "fees": [],
    "carrier_detail": null,
    "public_url": "https://track.easypost.com/djE6dHJrXzYxOGIzMTc2MTgxOTQyM2NiZDU4MjBjMTE5NDljZTQx"
  },
  "to_address": {
    "id": "adr_79050fa31f4711eea1a1ac1f6bc53342",
    "object": "Address",
    "created_at": "2023-07-10T17:30:32+00:00",
    "updated_at": "2023-07-10T17:30:33+00:00",
    "name": "DR. STEVE BRULE",
    "company": null,
    "street1": "179 N HARBOR DR",
    "street2": null,
    "city": "REDONDO BEACH",
    "state": "CA",
    "zip": "90277-2506",
    "country": "US",
    "phone": "8573875756",
    "email": "DR_STEVE_BRULE@GMAIL.COM",
    "mode": "test",
    "carrier_facility": null,
    "residential": false,
    "federal_tax_id": null,
    "state_tax_id": null,
    "verifications": {
      "zip4": {
        "success": true,
        "errors": [],
        "details": null
      },
      "delivery": {
        "success": true,
        "errors": [],
        "details": {
          "latitude": 33.8436,
          "longitude": -118.39177,
          "time_zone": "America/Los_Angeles"
        }
      }
    }
  },
  "usps_zone": 4,
  "return_address": {
    "id": "adr_790830351f4711ee972c3cecef1b359e",
    "object": "Address",
    "created_at": "2023-07-10T17:30:32+00:00",
    "updated_at": "2023-07-10T17:30:32+00:00",
    "name": "EasyPost",
    "company": null,
    "street1": "417 Montgomery Street",
    "street2": "5th Floor",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94104",
    "country": "US",
    "phone": "4153334445",
    "email": "support@easypost.com",
    "mode": "test",
    "carrier_facility": null,
    "residential": null,
    "federal_tax_id": null,
    "state_tax_id": null,
    "verifications": {}
  },
  "buyer_address": {
    "id": "adr_79050fa31f4711eea1a1ac1f6bc53342",
    "object": "Address",
    "created_at": "2023-07-10T17:30:32+00:00",
    "updated_at": "2023-07-10T17:30:33+00:00",
    "name": "DR. STEVE BRULE",
    "company": null,
    "street1": "179 N HARBOR DR",
    "street2": null,
    "city": "REDONDO BEACH",
    "state": "CA",
    "zip": "90277-2506",
    "country": "US",
    "phone": "8573875756",
    "email": "DR_STEVE_BRULE@GMAIL.COM",
    "mode": "test",
    "carrier_facility": null,
    "residential": false,
    "federal_tax_id": null,
    "state_tax_id": null,
    "verifications": {
      "zip4": {
        "success": true,
        "errors": [],
        "details": null
      },
      "delivery": {
        "success": true,
        "errors": [],
        "details": {
          "latitude": 33.8436,
          "longitude": -118.39177,
          "time_zone": "America/Los_Angeles"
        }
      }
    }
  },
  "forms": [],
  "fees": [
    {
      "object": "Fee",
      "type": "LabelFee",
      "amount": "0.00000",
      "charged": true,
      "refunded": false
    },
    {
      "object": "Fee",
      "type": "PostageFee",
      "amount": "7.47000",
      "charged": true,
      "refunded": false
    },
    {
      "object": "Fee",
      "type": "InsuranceFee",
      "amount": "2.49990",
      "charged": true,
      "refunded": false
    }
  ],
  "id": "shp_5948db965e944950b6acc052af7f79a1",
  "object": "Shipment"
}

POST/shipments

Buy a Shipment without rating (One-Call Buy)

There is an alternative way to purchase shipments that is known as the "one-call buy" method. This method is often used if you have a flat-rate set with a mail carrier for a given service level OR if you know your desired service level without needing to see the rate first.

Utilizing the "one-call buy" method can improve the performance of your integration, because it cuts out an API call from our standard "create shipment" then "buy shipment" workflow. In order to achieve this behavior all you have to do is add a single carrier account and service level name to your "Create Shipment" call.

Request Parameters

param	example	info
reference	"my-reference"	An optional field that may be used in place of id in other API endpoints
to_address	<Address>	Can be specified by ID or attributes to create a new one, and be verified inline. See Create and Verify Address
from_address	<Address>	Can be specified by ID or attributes to create a new one, and be verified inline. See Create and Verify Address
parcel	<Parcel>
carrier_accounts	["ca_..."]	List of carrier accounts
service	"Priority"	The service of carrier

Example

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Newtonsoft.Json;
using EasyPost;
using EasyPost.Models.API;
using EasyPost.Parameters;

namespace EasyPostExamples
{
    public class Examples
    {
        public static async Task Main()
        {
            string apiKey = Environment.GetEnvironmentVariable("EASYPOST_API_KEY")!;

            var client = new EasyPost.Client(apiKey);

            Parameters.Shipment.Create parameters = new()
            {
                ToAddress = new Parameters.Address.Create
                {
                    Name = "Dr. Steve Brule",
                    Street1 = "417 Montgomery Street",
                    Street2 = "5th Floor",
                    City = "San Francisco",
                    State = "CA",
                    Country = "US",
                    Zip = "94104"
                },
                FromAddress = new Parameters.Address.Create
                {
                    Company = "EasyPost",
                    Street1 = "417 Montgomery Street",
                    Street2 = "Floor 5",
                    City = "San Francisco",
                    State = "CA",
                    Country = "US",
                    Zip = "94104"
                },
                Parcel = new Parameters.Parcel.Create
                {
                    Length = 8,
                    Width = 6,
                    Height = 5,
                    Weight = 10
                },
                Service = "NextDayAir",
                CarrierAccountIds = new List<string> { "ca_..." }
            };

            Shipment shipment = await client.Shipment.Create(parameters);

            Console.WriteLine(JsonConvert.SerializeObject(shipment, Formatting.Indented));
        }
    }
}

{
  "created_at": "2022-10-27T16:55:16Z",
  "is_return": false,
  "messages": [],
  "mode": "test",
  "options": {
    "currency": "USD",
    "payment": {
      "type": "SENDER"
    },
    "date_advance": 0
  },
  "reference": null,
  "status": "unknown",
  "tracking_code": "9405500106068145794057",
  "updated_at": "2022-10-27T16:55:17Z",
  "batch_id": null,
  "batch_status": null,
  "batch_message": null,
  "customs_info": {
    "id": "cstinfo_cd38807b69ff417d849d3b014833b521",
    "object": "CustomsInfo",
    "created_at": "2022-10-27T16:55:16Z",
    "updated_at": "2022-10-27T16:55:16Z",
    "contents_explanation": "",
    "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",
    "mode": "test",
    "declaration": null,
    "customs_items": [
      {
        "id": "cstitem_2b2060940fc24c01b728f39d8fcf8dac",
        "object": "CustomsItem",
        "created_at": "2022-10-27T16:55:16Z",
        "updated_at": "2022-10-27T16:55:16Z",
        "description": "T-shirt",
        "hs_tariff_number": "123456",
        "origin_country": "US",
        "quantity": 1,
        "value": "10.0",
        "weight": 5.0,
        "code": "123",
        "mode": "test",
        "manufacturer": null,
        "currency": null,
        "eccn": null,
        "printed_commodity_identifier": null
      }
    ]
  },
  "from_address": {
    "id": "adr_21a919c7561811ed9652ac1f6bc72124",
    "object": "Address",
    "created_at": "2022-10-27T16:55:16+00:00",
    "updated_at": "2022-10-27T16:55:16+00:00",
    "name": "EasyPost",
    "company": null,
    "street1": "417 Montgomery Street",
    "street2": "5th Floor",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94104",
    "country": "US",
    "phone": "4153334445",
    "email": "support@easypost.com",
    "mode": "test",
    "carrier_facility": null,
    "residential": null,
    "federal_tax_id": null,
    "state_tax_id": null,
    "verifications": {}
  },
  "insurance": null,
  "order_id": null,
  "parcel": {
    "id": "prcl_a07f51976f1148948fd13dbc06da8e2c",
    "object": "Parcel",
    "created_at": "2022-10-27T16:55:16Z",
    "updated_at": "2022-10-27T16:55:16Z",
    "length": 20.2,
    "width": 10.9,
    "height": 5.0,
    "predefined_package": null,
    "weight": 65.9,
    "mode": "test"
  },
  "postage_label": {
    "object": "PostageLabel",
    "id": "pl_0422d418ba554cdbb71aa4155654c5bb",
    "created_at": "2022-10-27T16:55:16Z",
    "updated_at": "2022-10-27T16:55:17Z",
    "date_advance": 0,
    "integrated_form": "none",
    "label_date": "2022-10-27T16:55:16Z",
    "label_resolution": 300,
    "label_size": "4x6",
    "label_type": "default",
    "label_file_type": "image/png",
    "label_url": "https://easypost-files.s3.us-west-2.amazonaws.com/files/postage_label/20221027/960bbdc30bc844479d7516b87afea21f.png",
    "label_pdf_url": null,
    "label_zpl_url": null,
    "label_epl2_url": null,
    "label_file": null
  },
  "rates": [
    {
      "id": "rate_2385958e1961451f88bd19742d3d40fd",
      "object": "Rate",
      "created_at": "2022-10-27T16:55:16Z",
      "updated_at": "2022-10-27T16:55:16Z",
      "mode": "test",
      "service": "Express",
      "carrier": "USPS",
      "rate": "44.55",
      "currency": "USD",
      "retail_rate": "51.30",
      "retail_currency": "USD",
      "list_rate": "44.55",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": null,
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "est_delivery_days": null,
      "shipment_id": "shp_c2aab812a68549cc99a710053da0b063",
      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
    },
    {
      "id": "rate_c9a4291540bb4d71a34817bea9403d6e",
      "object": "Rate",
      "created_at": "2022-10-27T16:55:16Z",
      "updated_at": "2022-10-27T16:55:16Z",
      "mode": "test",
      "service": "Priority",
      "carrier": "USPS",
      "rate": "10.07",
      "currency": "USD",
      "retail_rate": "13.45",
      "retail_currency": "USD",
      "list_rate": "10.07",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": 2,
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "est_delivery_days": 2,
      "shipment_id": "shp_c2aab812a68549cc99a710053da0b063",
      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
    }
  ],
  "refund_status": null,
  "scan_form": null,
  "selected_rate": {
    "id": "rate_c9a4291540bb4d71a34817bea9403d6e",
    "object": "Rate",
    "created_at": "2022-10-27T16:55:16Z",
    "updated_at": "2022-10-27T16:55:16Z",
    "mode": "test",
    "service": "Priority",
    "carrier": "USPS",
    "rate": "10.07",
    "currency": "USD",
    "retail_rate": "13.45",
    "retail_currency": "USD",
    "list_rate": "10.07",
    "list_currency": "USD",
    "billing_type": "easypost",
    "delivery_days": 2,
    "delivery_date": null,
    "delivery_date_guaranteed": false,
    "est_delivery_days": 2,
    "shipment_id": "shp_c2aab812a68549cc99a710053da0b063",
    "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
  },
  "tracker": {
    "id": "trk_cabd8faadb134c81bf7cc5e20dc74077",
    "object": "Tracker",
    "mode": "test",
    "tracking_code": "9405500106068145794057",
    "status": "unknown",
    "status_detail": "unknown",
    "created_at": "2022-10-27T16:55:17Z",
    "updated_at": "2022-10-27T16:55:17Z",
    "signed_by": null,
    "weight": null,
    "est_delivery_date": null,
    "shipment_id": "shp_c2aab812a68549cc99a710053da0b063",
    "carrier": "USPS",
    "tracking_details": [],
    "fees": [],
    "carrier_detail": null,
    "public_url": "https://track.easypost.com/djE6dHJrX2NhYmQ4ZmFhZGIxMzRjODFiZjdjYzVlMjBkYzc0MDc3"
  },
  "to_address": {
    "id": "adr_21a73c5d561811ed9651ac1f6bc72124",
    "object": "Address",
    "created_at": "2022-10-27T16:55:16+00:00",
    "updated_at": "2022-10-27T16:55:16+00:00",
    "name": "DR. STEVE BRULE",
    "company": null,
    "street1": "179 N HARBOR DR",
    "street2": null,
    "city": "REDONDO BEACH",
    "state": "CA",
    "zip": "90277-2506",
    "country": "US",
    "phone": "8573875756",
    "email": "DR_STEVE_BRULE@GMAIL.COM",
    "mode": "test",
    "carrier_facility": null,
    "residential": false,
    "federal_tax_id": null,
    "state_tax_id": null,
    "verifications": {
      "zip4": {
        "success": true,
        "errors": [],
        "details": null
      },
      "delivery": {
        "success": true,
        "errors": [],
        "details": {
          "latitude": 33.8436,
          "longitude": -118.39177,
          "time_zone": "America/Los_Angeles"
        }
      }
    }
  },
  "usps_zone": 4,
  "return_address": {
    "id": "adr_21a919c7561811ed9652ac1f6bc72124",
    "object": "Address",
    "created_at": "2022-10-27T16:55:16+00:00",
    "updated_at": "2022-10-27T16:55:16+00:00",
    "name": "EasyPost",
    "company": null,
    "street1": "417 Montgomery Street",
    "street2": "5th Floor",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94104",
    "country": "US",
    "phone": "4153334445",
    "email": "support@easypost.com",
    "mode": "test",
    "carrier_facility": null,
    "residential": null,
    "federal_tax_id": null,
    "state_tax_id": null,
    "verifications": {}
  },
  "buyer_address": {
    "id": "adr_21a73c5d561811ed9651ac1f6bc72124",
    "object": "Address",
    "created_at": "2022-10-27T16:55:16+00:00",
    "updated_at": "2022-10-27T16:55:16+00:00",
    "name": "DR. STEVE BRULE",
    "company": null,
    "street1": "179 N HARBOR DR",
    "street2": null,
    "city": "REDONDO BEACH",
    "state": "CA",
    "zip": "90277-2506",
    "country": "US",
    "phone": "8573875756",
    "email": "DR_STEVE_BRULE@GMAIL.COM",
    "mode": "test",
    "carrier_facility": null,
    "residential": false,
    "federal_tax_id": null,
    "state_tax_id": null,
    "verifications": {
      "zip4": {
        "success": true,
        "errors": [],
        "details": null
      },
      "delivery": {
        "success": true,
        "errors": [],
        "details": {
          "latitude": 33.8436,
          "longitude": -118.39177,
          "time_zone": "America/Los_Angeles"
        }
      }
    }
  },
  "forms": [],
  "fees": [
    {
      "object": "Fee",
      "type": "LabelFee",
      "amount": "0.00000",
      "charged": true,
      "refunded": false
    },
    {
      "object": "Fee",
      "type": "PostageFee",
      "amount": "10.07000",
      "charged": true,
      "refunded": false
    }
  ],
  "id": "shp_c2aab812a68549cc99a710053da0b063",
  "object": "Shipment"
}

GET/shipments/:id/label

Convert the Label format of a Shipment

A Shipment's PostageLabel can be converted from PNG to other formats. To convert a PostageLabel, the original must be a PNG. Converting labels works best when they are 4x6 labels converted from PNG to ZPL.

Example

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Newtonsoft.Json;
using EasyPost;
using EasyPost.Models.API;
using EasyPost.Parameters;

namespace EasyPostExamples
{
    public class Examples
    {
        public static async Task Main()
        {
            string apiKey = Environment.GetEnvironmentVariable("EASYPOST_API_KEY")!;

            var client = new EasyPost.Client(apiKey);

            Shipment shipment = await client.Shipment.Retrieve("shp_...");

            Parameters.Shipment.GenerateLabel parameters = new()
            {
                FileFormat = "ZPL",
            };

            shipment = await client.Shipment.GenerateLabel(shipment.Id, parameters);

            Console.WriteLine(JsonConvert.SerializeObject(shipment, Formatting.Indented));
        }
    }
}

{
  "created_at": "2023-07-10T17:30:35Z",
  "is_return": false,
  "messages": [],
  "mode": "test",
  "options": {
    "currency": "USD",
    "payment": {
      "type": "SENDER"
    },
    "date_advance": 0
  },
  "reference": null,
  "status": "unknown",
  "tracking_code": "9405500105440232839178",
  "updated_at": "2023-07-10T17:30:37Z",
  "batch_id": null,
  "batch_status": null,
  "batch_message": null,
  "customs_info": {
    "id": "cstinfo_8a7a128a4d484e629d1df17c6574d465",
    "object": "CustomsInfo",
    "created_at": "2023-07-10T17:30:35Z",
    "updated_at": "2023-07-10T17:30:35Z",
    "contents_explanation": "",
    "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",
    "mode": "test",
    "declaration": null,
    "customs_items": [
      {
        "id": "cstitem_27cfd5bf8f644a7e931a41fcf06330a2",
        "object": "CustomsItem",
        "created_at": "2023-07-10T17:30:35Z",
        "updated_at": "2023-07-10T17:30:35Z",
        "description": "T-shirt",
        "hs_tariff_number": "123456",
        "origin_country": "US",
        "quantity": 1,
        "value": "10.0",
        "weight": 5.0,
        "code": "123",
        "mode": "test",
        "manufacturer": null,
        "currency": null,
        "eccn": null,
        "printed_commodity_identifier": null
      }
    ]
  },
  "from_address": {
    "id": "adr_7aba54831f4711ee98223cecef1b359e",
    "object": "Address",
    "created_at": "2023-07-10T17:30:35+00:00",
    "updated_at": "2023-07-10T17:30:35+00:00",
    "name": "EasyPost",
    "company": null,
    "street1": "417 Montgomery Street",
    "street2": "5th Floor",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94104",
    "country": "US",
    "phone": "4153334445",
    "email": "support@easypost.com",
    "mode": "test",
    "carrier_facility": null,
    "residential": null,
    "federal_tax_id": null,
    "state_tax_id": null,
    "verifications": {}
  },
  "insurance": null,
  "order_id": null,
  "parcel": {
    "id": "prcl_8dabc97f439e403eac391487526d0d35",
    "object": "Parcel",
    "created_at": "2023-07-10T17:30:35Z",
    "updated_at": "2023-07-10T17:30:35Z",
    "length": 20.2,
    "width": 10.9,
    "height": 5.0,
    "predefined_package": null,
    "weight": 65.9,
    "mode": "test"
  },
  "postage_label": {
    "object": "PostageLabel",
    "id": "pl_a715f79f92b84a459983bd7948e0aa46",
    "created_at": "2023-07-10T17:30:37Z",
    "updated_at": "2023-07-10T17:30:39Z",
    "date_advance": 0,
    "integrated_form": "none",
    "label_date": "2023-07-10T17:30:37Z",
    "label_resolution": 300,
    "label_size": "4x6",
    "label_type": "default",
    "label_file_type": "image/png",
    "label_url": "https://easypost-files.s3.us-west-2.amazonaws.com/files/postage_label/20230710/e6cd61789cbe534ad7a16c2ac479c747d5.png",
    "label_pdf_url": null,
    "label_zpl_url": "https://easypost-files.s3-us-west-2.amazonaws.com/files/postage_label/20230710/d649677a74d247f6929f97ab37fd9036.zpl",
    "label_epl2_url": null,
    "label_file": null
  },
  "rates": [
    {
      "id": "rate_7fff965d5e6f42bbb53151764d47323a",
      "object": "Rate",
      "created_at": "2023-07-10T17:30:36Z",
      "updated_at": "2023-07-10T17:30:36Z",
      "mode": "test",
      "service": "Priority",
      "carrier": "USPS",
      "rate": "7.47",
      "currency": "USD",
      "retail_rate": "14.05",
      "retail_currency": "USD",
      "list_rate": "10.27",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": 2,
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "est_delivery_days": 2,
      "shipment_id": "shp_876e40a52920430fbcb5bc6dde09d804",
      "carrier_account_id": "ca_b25657e9896e4d63ac8151ac346ac41e"
    },
    {
      "id": "rate_d88c3fdef34840af904295a80ec50e66",
      "object": "Rate",
      "created_at": "2023-07-10T17:30:36Z",
      "updated_at": "2023-07-10T17:30:36Z",
      "mode": "test",
      "service": "GroundAdvantage",
      "carrier": "USPS",
      "rate": "8.92",
      "currency": "USD",
      "retail_rate": "8.92",
      "retail_currency": "USD",
      "list_rate": "8.92",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": null,
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "est_delivery_days": null,
      "shipment_id": "shp_876e40a52920430fbcb5bc6dde09d804",
      "carrier_account_id": "ca_b25657e9896e4d63ac8151ac346ac41e"
    },
    {
      "id": "rate_a4f782c90e244d1388bdb4a2f2c2075d",
      "object": "Rate",
      "created_at": "2023-07-10T17:30:36Z",
      "updated_at": "2023-07-10T17:30:36Z",
      "mode": "test",
      "service": "First",
      "carrier": "USPS",
      "rate": "8.92",
      "currency": "USD",
      "retail_rate": "8.92",
      "retail_currency": "USD",
      "list_rate": "8.92",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": 3,
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "est_delivery_days": 3,
      "shipment_id": "shp_876e40a52920430fbcb5bc6dde09d804",
      "carrier_account_id": "ca_b25657e9896e4d63ac8151ac346ac41e"
    },
    {
      "id": "rate_0fdf58026db749fbb61435b5cfaa609b",
      "object": "Rate",
      "created_at": "2023-07-10T17:30:36Z",
      "updated_at": "2023-07-10T17:30:36Z",
      "mode": "test",
      "service": "Express",
      "carrier": "USPS",
      "rate": "46.85",
      "currency": "USD",
      "retail_rate": "54.20",
      "retail_currency": "USD",
      "list_rate": "46.85",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": null,
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "est_delivery_days": null,
      "shipment_id": "shp_876e40a52920430fbcb5bc6dde09d804",
      "carrier_account_id": "ca_b25657e9896e4d63ac8151ac346ac41e"
    }
  ],
  "refund_status": null,
  "scan_form": null,
  "selected_rate": {
    "id": "rate_7fff965d5e6f42bbb53151764d47323a",
    "object": "Rate",
    "created_at": "2023-07-10T17:30:37Z",
    "updated_at": "2023-07-10T17:30:37Z",
    "mode": "test",
    "service": "Priority",
    "carrier": "USPS",
    "rate": "7.47",
    "currency": "USD",
    "retail_rate": "14.05",
    "retail_currency": "USD",
    "list_rate": "10.27",
    "list_currency": "USD",
    "billing_type": "easypost",
    "delivery_days": 2,
    "delivery_date": null,
    "delivery_date_guaranteed": false,
    "est_delivery_days": 2,
    "shipment_id": "shp_876e40a52920430fbcb5bc6dde09d804",
    "carrier_account_id": "ca_b25657e9896e4d63ac8151ac346ac41e"
  },
  "tracker": {
    "id": "trk_d4a96654a82d4b22aefbd0f7205f3e09",
    "object": "Tracker",
    "mode": "test",
    "tracking_code": "9405500105440232839178",
    "status": "pre_transit",
    "status_detail": "status_update",
    "created_at": "2023-07-10T17:30:37Z",
    "updated_at": "2023-07-10T17:30:37Z",
    "signed_by": null,
    "weight": null,
    "est_delivery_date": "2023-07-10T17:30:37Z",
    "shipment_id": "shp_876e40a52920430fbcb5bc6dde09d804",
    "carrier": "USPS",
    "tracking_details": [
      {
        "object": "TrackingDetail",
        "message": "Pre-Shipment Info Sent to USPS",
        "description": null,
        "status": "pre_transit",
        "status_detail": "status_update",
        "datetime": "2023-06-10T17:30:37Z",
        "source": "USPS",
        "carrier_code": null,
        "tracking_location": {
          "object": "TrackingLocation",
          "city": null,
          "state": null,
          "country": null,
          "zip": null
        }
      },
      {
        "object": "TrackingDetail",
        "message": "Shipping Label Created",
        "description": null,
        "status": "pre_transit",
        "status_detail": "status_update",
        "datetime": "2023-06-11T06:07:37Z",
        "source": "USPS",
        "carrier_code": null,
        "tracking_location": {
          "object": "TrackingLocation",
          "city": "HOUSTON",
          "state": "TX",
          "country": null,
          "zip": "77063"
        }
      }
    ],
    "fees": [],
    "carrier_detail": {
      "object": "CarrierDetail",
      "service": "First-Class Package Service",
      "container_type": null,
      "est_delivery_date_local": null,
      "est_delivery_time_local": null,
      "origin_location": "HOUSTON TX, 77001",
      "origin_tracking_location": {
        "object": "TrackingLocation",
        "city": "HOUSTON",
        "state": "TX",
        "country": null,
        "zip": "77063"
      },
      "destination_location": "CHARLESTON SC, 29401",
      "destination_tracking_location": null,
      "guaranteed_delivery_date": null,
      "alternate_identifier": null,
      "initial_delivery_attempt": null
    },
    "public_url": "https://track.easypost.com/djE6dHJrX2Q0YTk2NjU0YTgyZDRiMjJhZWZiZDBmNzIwNWYzZTA5"
  },
  "to_address": {
    "id": "adr_7ab7b7ef1f4711ee981f3cecef1b359e",
    "object": "Address",
    "created_at": "2023-07-10T17:30:35+00:00",
    "updated_at": "2023-07-10T17:30:36+00:00",
    "name": "DR. STEVE BRULE",
    "company": null,
    "street1": "179 N HARBOR DR",
    "street2": null,
    "city": "REDONDO BEACH",
    "state": "CA",
    "zip": "90277-2506",
    "country": "US",
    "phone": "8573875756",
    "email": "DR_STEVE_BRULE@GMAIL.COM",
    "mode": "test",
    "carrier_facility": null,
    "residential": false,
    "federal_tax_id": null,
    "state_tax_id": null,
    "verifications": {
      "zip4": {
        "success": true,
        "errors": [],
        "details": null
      },
      "delivery": {
        "success": true,
        "errors": [],
        "details": {
          "latitude": 33.8436,
          "longitude": -118.39177,
          "time_zone": "America/Los_Angeles"
        }
      }
    }
  },
  "usps_zone": 4,
  "return_address": {
    "id": "adr_7aba54831f4711ee98223cecef1b359e",
    "object": "Address",
    "created_at": "2023-07-10T17:30:35+00:00",
    "updated_at": "2023-07-10T17:30:35+00:00",
    "name": "EasyPost",
    "company": null,
    "street1": "417 Montgomery Street",
    "street2": "5th Floor",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94104",
    "country": "US",
    "phone": "4153334445",
    "email": "support@easypost.com",
    "mode": "test",
    "carrier_facility": null,
    "residential": null,
    "federal_tax_id": null,
    "state_tax_id": null,
    "verifications": {}
  },
  "buyer_address": {
    "id": "adr_7ab7b7ef1f4711ee981f3cecef1b359e",
    "object": "Address",
    "created_at": "2023-07-10T17:30:35+00:00",
    "updated_at": "2023-07-10T17:30:36+00:00",
    "name": "DR. STEVE BRULE",
    "company": null,
    "street1": "179 N HARBOR DR",
    "street2": null,
    "city": "REDONDO BEACH",
    "state": "CA",
    "zip": "90277-2506",
    "country": "US",
    "phone": "8573875756",
    "email": "DR_STEVE_BRULE@GMAIL.COM",
    "mode": "test",
    "carrier_facility": null,
    "residential": false,
    "federal_tax_id": null,
    "state_tax_id": null,
    "verifications": {
      "zip4": {
        "success": true,
        "errors": [],
        "details": null
      },
      "delivery": {
        "success": true,
        "errors": [],
        "details": {
          "latitude": 33.8436,
          "longitude": -118.39177,
          "time_zone": "America/Los_Angeles"
        }
      }
    }
  },
  "forms": [],
  "fees": [
    {
      "object": "Fee",
      "type": "LabelFee",
      "amount": "0.00000",
      "charged": true,
      "refunded": false
    },
    {
      "object": "Fee",
      "type": "PostageFee",
      "amount": "7.47000",
      "charged": true,
      "refunded": false
    }
  ],
  "id": "shp_876e40a52920430fbcb5bc6dde09d804",
  "object": "Shipment"
}

Carbon Offset

The Carbon Offset API estimates the carbon emissions on parcel delivery for a given shipment, and allows purchasing offsets to neutralize carbon emissions from parcel delivery.

To use the Carbon Offset API, set carbon_offset to "true" when creating a Shipment. Each Rate will return a CarbonOffset object with the estimated grams of carbon emitted and price to offset the carbon emissions. To purchase the carbon offset, set carbon_offset to "true" when you purchase the Shipment.

If no offset is available for a shipment when requested, a message "No carbon offset available for this shipment" is shown in the messages array.

Carbon Offset Object

attribute	type	specification
grams	integer	the estimated amount of carbon grams emitted by the shipment
price	string	price to offset the amount of carbon grams
currency	string	currency of the price (currently always USD)
object	string	"CarbonOffset"

POST/shipments

Create Shipment with Carbon Offset

Request Parameters

param	example	info
carbon_offset	true	Whether you want to buy a shipment with carbon offset.

Example

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Newtonsoft.Json;
using EasyPost;
using EasyPost.Models.API;
using EasyPost.Parameters;

namespace EasyPostExamples
{
    public class Examples
    {
        public static async Task Main()
        {
            string apiKey = Environment.GetEnvironmentVariable("EASYPOST_API_KEY")!;

            var client = new EasyPost.Client(apiKey);

            Parameters.Shipment.Create parameters = new()
            {
                ToAddress = new Parameters.Address.Create
                {
                    Name = "Dr. Steve Brule",
                    Street1 = "417 Montgomery Street",
                    Street2 = "5th Floor",
                    City = "San Francisco",
                    State = "CA",
                    Country = "US",
                    Zip = "94104"
                },
                FromAddress = new Parameters.Address.Create
                {
                    Company = "EasyPost",
                    Street1 = "417 Montgomery Street",
                    Street2 = "Floor 5",
                    City = "San Francisco",
                    State = "CA",
                    Country = "US",
                    Zip = "94104"
                },
                Parcel = new Parameters.Parcel.Create
                {
                    Length = 20.2,
                    Width = 10.9,
                    Height = 5,
                    Weight = 65.9
                },
                Reference = "ShipmentRef",
                CarbonOffset = true
            };

            Shipment shipment = await client.Shipment.Create(parameters);

            Console.WriteLine(JsonConvert.SerializeObject(shipment, Formatting.Indented));
        }
    }
}

{
  "created_at": "2023-07-10T17:29:51Z",
  "is_return": false,
  "messages": [],
  "mode": "test",
  "options": {
    "currency": "USD",
    "payment": {
      "type": "SENDER"
    },
    "date_advance": 0
  },
  "reference": null,
  "status": "unknown",
  "tracking_code": null,
  "updated_at": "2023-07-10T17:29:52Z",
  "batch_id": null,
  "batch_status": null,
  "batch_message": null,
  "customs_info": {
    "id": "cstinfo_3ced3c21acbe4d7c97d80563426466f4",
    "object": "CustomsInfo",
    "created_at": "2023-07-10T17:29:51Z",
    "updated_at": "2023-07-10T17:29:51Z",
    "contents_explanation": "",
    "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",
    "mode": "test",
    "declaration": null,
    "customs_items": [
      {
        "id": "cstitem_cd3206de7e60412d8a1c5331d0e6260a",
        "object": "CustomsItem",
        "created_at": "2023-07-10T17:29:51Z",
        "updated_at": "2023-07-10T17:29:51Z",
        "description": "T-shirt",
        "hs_tariff_number": "123456",
        "origin_country": "US",
        "quantity": 1,
        "value": "10.0",
        "weight": 5.0,
        "code": "123",
        "mode": "test",
        "manufacturer": null,
        "currency": null,
        "eccn": null,
        "printed_commodity_identifier": null
      }
    ]
  },
  "from_address": {
    "id": "adr_609f0edb1f4711ee89653cecef1b359e",
    "object": "Address",
    "created_at": "2023-07-10T17:29:51+00:00",
    "updated_at": "2023-07-10T17:29:51+00:00",
    "name": "EasyPost",
    "company": null,
    "street1": "417 Montgomery Street",
    "street2": "5th Floor",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94104",
    "country": "US",
    "phone": "4153334445",
    "email": "support@easypost.com",
    "mode": "test",
    "carrier_facility": null,
    "residential": null,
    "federal_tax_id": null,
    "state_tax_id": null,
    "verifications": {}
  },
  "insurance": null,
  "order_id": null,
  "parcel": {
    "id": "prcl_e0b5c177be934e0ea0988747fd972e66",
    "object": "Parcel",
    "created_at": "2023-07-10T17:29:51Z",
    "updated_at": "2023-07-10T17:29:51Z",
    "length": 20.2,
    "width": 10.9,
    "height": 5.0,
    "predefined_package": null,
    "weight": 65.9,
    "mode": "test"
  },
  "postage_label": null,
  "rates": [
    {
      "id": "rate_ef07644f6cfc4e69b7d03cad108773ff",
      "object": "Rate",
      "created_at": "2023-07-10T17:29:52Z",
      "updated_at": "2023-07-10T17:29:52Z",
      "mode": "test",
      "service": "Priority",
      "carrier": "USPS",
      "rate": "7.47",
      "currency": "USD",
      "retail_rate": "14.05",
      "retail_currency": "USD",
      "list_rate": "10.27",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": 2,
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "est_delivery_days": 2,
      "shipment_id": "shp_afd3b386dff940b88a521ef42bb67ef1",
      "carrier_account_id": "ca_b25657e9896e4d63ac8151ac346ac41e",
      "carbon_offset": {
        "object": "CarbonOffset",
        "grams": 154,
        "price": "0.11",
        "currency": "USD"
      }
    },
    {
      "id": "rate_2d1075bb37044e0d85b4c813c620ee65",
      "object": "Rate",
      "created_at": "2023-07-10T17:29:52Z",
      "updated_at": "2023-07-10T17:29:52Z",
      "mode": "test",
      "service": "GroundAdvantage",
      "carrier": "USPS",
      "rate": "8.92",
      "currency": "USD",
      "retail_rate": "8.92",
      "retail_currency": "USD",
      "list_rate": "8.92",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": null,
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "est_delivery_days": null,
      "shipment_id": "shp_afd3b386dff940b88a521ef42bb67ef1",
      "carrier_account_id": "ca_b25657e9896e4d63ac8151ac346ac41e",
      "carbon_offset": {
        "object": "CarbonOffset",
        "grams": 154,
        "price": "0.11",
        "currency": "USD"
      }
    },
    {
      "id": "rate_992b27e562594bdd968b1d951073e1b0",
      "object": "Rate",
      "created_at": "2023-07-10T17:29:52Z",
      "updated_at": "2023-07-10T17:29:52Z",
      "mode": "test",
      "service": "First",
      "carrier": "USPS",
      "rate": "8.92",
      "currency": "USD",
      "retail_rate": "8.92",
      "retail_currency": "USD",
      "list_rate": "8.92",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": 3,
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "est_delivery_days": 3,
      "shipment_id": "shp_afd3b386dff940b88a521ef42bb67ef1",
      "carrier_account_id": "ca_b25657e9896e4d63ac8151ac346ac41e",
      "carbon_offset": {
        "object": "CarbonOffset",
        "grams": 154,
        "price": "0.11",
        "currency": "USD"
      }
    },
    {
      "id": "rate_1f38a0d7777f4a13a610c6684179ab13",
      "object": "Rate",
      "created_at": "2023-07-10T17:29:52Z",
      "updated_at": "2023-07-10T17:29:52Z",
      "mode": "test",
      "service": "Express",
      "carrier": "USPS",
      "rate": "46.85",
      "currency": "USD",
      "retail_rate": "54.20",
      "retail_currency": "USD",
      "list_rate": "46.85",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": null,
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "est_delivery_days": null,
      "shipment_id": "shp_afd3b386dff940b88a521ef42bb67ef1",
      "carrier_account_id": "ca_b25657e9896e4d63ac8151ac346ac41e",
      "carbon_offset": {
        "object": "CarbonOffset",
        "grams": 154,
        "price": "0.11",
        "currency": "USD"
      }
    }
  ],
  "refund_status": null,
  "scan_form": null,
  "selected_rate": null,
  "tracker": null,
  "to_address": {
    "id": "adr_609d2c911f4711ee9971ac1f6bc53342",
    "object": "Address",
    "created_at": "2023-07-10T17:29:51+00:00",
    "updated_at": "2023-07-10T17:29:51+00:00",
    "name": "Dr. Steve Brule",
    "company": null,
    "street1": "179 N Harbor Dr",
    "street2": null,
    "city": "Redondo Beach",
    "state": "CA",
    "zip": "90277",
    "country": "US",
    "phone": "8573875756",
    "email": "dr_steve_brule@gmail.com",
    "mode": "test",
    "carrier_facility": null,
    "residential": null,
    "federal_tax_id": null,
    "state_tax_id": null,
    "verifications": {}
  },
  "usps_zone": 4,
  "return_address": {
    "id": "adr_609f0edb1f4711ee89653cecef1b359e",
    "object": "Address",
    "created_at": "2023-07-10T17:29:51+00:00",
    "updated_at": "2023-07-10T17:29:51+00:00",
    "name": "EasyPost",
    "company": null,
    "street1": "417 Montgomery Street",
    "street2": "5th Floor",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94104",
    "country": "US",
    "phone": "4153334445",
    "email": "support@easypost.com",
    "mode": "test",
    "carrier_facility": null,
    "residential": null,
    "federal_tax_id": null,
    "state_tax_id": null,
    "verifications": {}
  },
  "buyer_address": {
    "id": "adr_609d2c911f4711ee9971ac1f6bc53342",
    "object": "Address",
    "created_at": "2023-07-10T17:29:51+00:00",
    "updated_at": "2023-07-10T17:29:51+00:00",
    "name": "Dr. Steve Brule",
    "company": null,
    "street1": "179 N Harbor Dr",
    "street2": null,
    "city": "Redondo Beach",
    "state": "CA",
    "zip": "90277",
    "country": "US",
    "phone": "8573875756",
    "email": "dr_steve_brule@gmail.com",
    "mode": "test",
    "carrier_facility": null,
    "residential": null,
    "federal_tax_id": null,
    "state_tax_id": null,
    "verifications": {}
  },
  "forms": [],
  "fees": [],
  "id": "shp_afd3b386dff940b88a521ef42bb67ef1",
  "object": "Shipment"
}

POST/shipments/:id/buy

Buy Shipment with Carbon Offset

Request Parameters

param	example	info
carbon_offset	true	Whether you want to buy a shipment with carbon offset.

Example

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Newtonsoft.Json;
using EasyPost;
using EasyPost.Models.API;
using EasyPost.Parameters;

namespace EasyPostExamples
{
    public class Examples
    {
        public static async Task Main()
        {
            string apiKey = Environment.GetEnvironmentVariable("EASYPOST_API_KEY")!;

            var client = new EasyPost.Client(apiKey);

            Shipment shipment = await client.Shipment.Retrieve("shp_...");

            Rate rate = shipment.LowestRate();

            Parameters.Shipment.Buy parameters = new(rate)
            {
                CarbonOffset = true,
            };

            shipment = await client.Shipment.Buy(shipment.Id, parameters);

            Console.WriteLine(JsonConvert.SerializeObject(shipment, Formatting.Indented));
        }
    }
}

{
  "created_at": "2023-07-10T17:29:53Z",
  "is_return": false,
  "messages": [],
  "mode": "test",
  "options": {
    "currency": "USD",
    "payment": {
      "type": "SENDER"
    },
    "date_advance": 0
  },
  "reference": null,
  "status": "unknown",
  "tracking_code": "9405500105440232838607",
  "updated_at": "2023-07-10T17:29:55Z",
  "batch_id": null,
  "batch_status": null,
  "batch_message": null,
  "customs_info": {
    "id": "cstinfo_c4daaab774984ac592444a0061c781f0",
    "object": "CustomsInfo",
    "created_at": "2023-07-10T17:29:53Z",
    "updated_at": "2023-07-10T17:29:53Z",
    "contents_explanation": "",
    "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",
    "mode": "test",
    "declaration": null,
    "customs_items": [
      {
        "id": "cstitem_a0822940d1f0421a9b6670d4381753b2",
        "object": "CustomsItem",
        "created_at": "2023-07-10T17:29:53Z",
        "updated_at": "2023-07-10T17:29:53Z",
        "description": "T-shirt",
        "hs_tariff_number": "123456",
        "origin_country": "US",
        "quantity": 1,
        "value": "10.0",
        "weight": 5.0,
        "code": "123",
        "mode": "test",
        "manufacturer": null,
        "currency": null,
        "eccn": null,
        "printed_commodity_identifier": null
      }
    ]
  },
  "from_address": {
    "id": "adr_616ebeab1f4711eea60bac1f6bc539ae",
    "object": "Address",
    "created_at": "2023-07-10T17:29:53+00:00",
    "updated_at": "2023-07-10T17:29:53+00:00",
    "name": "EasyPost",
    "company": null,
    "street1": "417 Montgomery Street",
    "street2": "5th Floor",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94104",
    "country": "US",
    "phone": "4153334445",
    "email": "support@easypost.com",
    "mode": "test",
    "carrier_facility": null,
    "residential": null,
    "federal_tax_id": null,
    "state_tax_id": null,
    "verifications": {}
  },
  "insurance": null,
  "order_id": null,
  "parcel": {
    "id": "prcl_b9d13559b82f47e5ab55f4c3e976a6b8",
    "object": "Parcel",
    "created_at": "2023-07-10T17:29:53Z",
    "updated_at": "2023-07-10T17:29:53Z",
    "length": 20.2,
    "width": 10.9,
    "height": 5.0,
    "predefined_package": null,
    "weight": 65.9,
    "mode": "test"
  },
  "postage_label": {
    "object": "PostageLabel",
    "id": "pl_baa95bd674b54650a1a25a8fab69a3cc",
    "created_at": "2023-07-10T17:29:55Z",
    "updated_at": "2023-07-10T17:29:55Z",
    "date_advance": 0,
    "integrated_form": "none",
    "label_date": "2023-07-10T17:29:55Z",
    "label_resolution": 300,
    "label_size": "4x6",
    "label_type": "default",
    "label_file_type": "image/png",
    "label_url": "https://easypost-files.s3.us-west-2.amazonaws.com/files/postage_label/20230710/e695109f6dc0174d2581fd37634db7f7dc.png",
    "label_pdf_url": null,
    "label_zpl_url": null,
    "label_epl2_url": null,
    "label_file": null
  },
  "rates": [
    {
      "id": "rate_4da9c6d82c09432b9f7572d9c2450dec",
      "object": "Rate",
      "created_at": "2023-07-10T17:29:53Z",
      "updated_at": "2023-07-10T17:29:53Z",
      "mode": "test",
      "service": "Priority",
      "carrier": "USPS",
      "rate": "7.47",
      "currency": "USD",
      "retail_rate": "14.05",
      "retail_currency": "USD",
      "list_rate": "10.27",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": 2,
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "est_delivery_days": 2,
      "shipment_id": "shp_90e86b79219e438f9b7aa0892dd51da9",
      "carrier_account_id": "ca_b25657e9896e4d63ac8151ac346ac41e",
      "carbon_offset": {
        "object": "CarbonOffset",
        "grams": 154,
        "price": "0.11",
        "currency": "USD"
      }
    },
    {
      "id": "rate_3c9d05495bc74c5cb8ee688443ef86b9",
      "object": "Rate",
      "created_at": "2023-07-10T17:29:53Z",
      "updated_at": "2023-07-10T17:29:53Z",
      "mode": "test",
      "service": "GroundAdvantage",
      "carrier": "USPS",
      "rate": "8.92",
      "currency": "USD",
      "retail_rate": "8.92",
      "retail_currency": "USD",
      "list_rate": "8.92",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": null,
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "est_delivery_days": null,
      "shipment_id": "shp_90e86b79219e438f9b7aa0892dd51da9",
      "carrier_account_id": "ca_b25657e9896e4d63ac8151ac346ac41e",
      "carbon_offset": {
        "object": "CarbonOffset",
        "grams": 154,
        "price": "0.11",
        "currency": "USD"
      }
    },
    {
      "id": "rate_6227e0be87184dd6bfc3be0f59fe569c",
      "object": "Rate",
      "created_at": "2023-07-10T17:29:53Z",
      "updated_at": "2023-07-10T17:29:53Z",
      "mode": "test",
      "service": "First",
      "carrier": "USPS",
      "rate": "8.92",
      "currency": "USD",
      "retail_rate": "8.92",
      "retail_currency": "USD",
      "list_rate": "8.92",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": 3,
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "est_delivery_days": 3,
      "shipment_id": "shp_90e86b79219e438f9b7aa0892dd51da9",
      "carrier_account_id": "ca_b25657e9896e4d63ac8151ac346ac41e",
      "carbon_offset": {
        "object": "CarbonOffset",
        "grams": 154,
        "price": "0.11",
        "currency": "USD"
      }
    },
    {
      "id": "rate_52a880007bde460f891fe87ecfc2e781",
      "object": "Rate",
      "created_at": "2023-07-10T17:29:54Z",
      "updated_at": "2023-07-10T17:29:54Z",
      "mode": "test",
      "service": "Express",
      "carrier": "USPS",
      "rate": "46.85",
      "currency": "USD",
      "retail_rate": "54.20",
      "retail_currency": "USD",
      "list_rate": "46.85",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": null,
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "est_delivery_days": null,
      "shipment_id": "shp_90e86b79219e438f9b7aa0892dd51da9",
      "carrier_account_id": "ca_b25657e9896e4d63ac8151ac346ac41e",
      "carbon_offset": {
        "object": "CarbonOffset",
        "grams": 154,
        "price": "0.11",
        "currency": "USD"
      }
    }
  ],
  "refund_status": null,
  "scan_form": null,
  "selected_rate": {
    "id": "rate_4da9c6d82c09432b9f7572d9c2450dec",
    "object": "Rate",
    "created_at": "2023-07-10T17:29:55Z",
    "updated_at": "2023-07-10T17:29:55Z",
    "mode": "test",
    "service": "Priority",
    "carrier": "USPS",
    "rate": "7.47",
    "currency": "USD",
    "retail_rate": "14.05",
    "retail_currency": "USD",
    "list_rate": "10.27",
    "list_currency": "USD",
    "billing_type": "easypost",
    "delivery_days": 2,
    "delivery_date": null,
    "delivery_date_guaranteed": false,
    "est_delivery_days": 2,
    "shipment_id": "shp_90e86b79219e438f9b7aa0892dd51da9",
    "carrier_account_id": "ca_b25657e9896e4d63ac8151ac346ac41e"
  },
  "tracker": {
    "id": "trk_d7c98516f41241a3adfefa7b3b5dbd8e",
    "object": "Tracker",
    "mode": "test",
    "tracking_code": "9405500105440232838607",
    "status": "unknown",
    "status_detail": "unknown",
    "created_at": "2023-07-10T17:29:55Z",
    "updated_at": "2023-07-10T17:29:55Z",
    "signed_by": null,
    "weight": null,
    "est_delivery_date": null,
    "shipment_id": "shp_90e86b79219e438f9b7aa0892dd51da9",
    "carrier": "USPS",
    "tracking_details": [],
    "fees": [],
    "carrier_detail": null,
    "public_url": "https://track.easypost.com/djE6dHJrX2Q3Yzk4NTE2ZjQxMjQxYTNhZGZlZmE3YjNiNWRiZDhl"
  },
  "to_address": {
    "id": "adr_616b0b911f4711ee89b13cecef1b359e",
    "object": "Address",
    "created_at": "2023-07-10T17:29:53+00:00",
    "updated_at": "2023-07-10T17:29:54+00:00",
    "name": "DR. STEVE BRULE",
    "company": null,
    "street1": "179 N HARBOR DR",
    "street2": null,
    "city": "REDONDO BEACH",
    "state": "CA",
    "zip": "90277-2506",
    "country": "US",
    "phone": "8573875756",
    "email": "DR_STEVE_BRULE@GMAIL.COM",
    "mode": "test",
    "carrier_facility": null,
    "residential": false,
    "federal_tax_id": null,
    "state_tax_id": null,
    "verifications": {
      "zip4": {
        "success": true,
        "errors": [],
        "details": null
      },
      "delivery": {
        "success": true,
        "errors": [],
        "details": {
          "latitude": 33.8436,
          "longitude": -118.39177,
          "time_zone": "America/Los_Angeles"
        }
      }
    }
  },
  "usps_zone": 4,
  "return_address": {
    "id": "adr_616ebeab1f4711eea60bac1f6bc539ae",
    "object": "Address",
    "created_at": "2023-07-10T17:29:53+00:00",
    "updated_at": "2023-07-10T17:29:53+00:00",
    "name": "EasyPost",
    "company": null,
    "street1": "417 Montgomery Street",
    "street2": "5th Floor",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94104",
    "country": "US",
    "phone": "4153334445",
    "email": "support@easypost.com",
    "mode": "test",
    "carrier_facility": null,
    "residential": null,
    "federal_tax_id": null,
    "state_tax_id": null,
    "verifications": {}
  },
  "buyer_address": {
    "id": "adr_616b0b911f4711ee89b13cecef1b359e",
    "object": "Address",
    "created_at": "2023-07-10T17:29:53+00:00",
    "updated_at": "2023-07-10T17:29:54+00:00",
    "name": "DR. STEVE BRULE",
    "company": null,
    "street1": "179 N HARBOR DR",
    "street2": null,
    "city": "REDONDO BEACH",
    "state": "CA",
    "zip": "90277-2506",
    "country": "US",
    "phone": "8573875756",
    "email": "DR_STEVE_BRULE@GMAIL.COM",
    "mode": "test",
    "carrier_facility": null,
    "residential": false,
    "federal_tax_id": null,
    "state_tax_id": null,
    "verifications": {
      "zip4": {
        "success": true,
        "errors": [],
        "details": null
      },
      "delivery": {
        "success": true,
        "errors": [],
        "details": {
          "latitude": 33.8436,
          "longitude": -118.39177,
          "time_zone": "America/Los_Angeles"
        }
      }
    }
  },
  "forms": [],
  "fees": [
    {
      "object": "Fee",
      "type": "LabelFee",
      "amount": "0.00000",
      "charged": true,
      "refunded": false
    },
    {
      "object": "Fee",
      "type": "PostageFee",
      "amount": "7.47000",
      "charged": true,
      "refunded": false
    },
    {
      "object": "Fee",
      "type": "CarbonOffsetFee",
      "amount": "0.11000",
      "charged": true,
      "refunded": false
    }
  ],
  "id": "shp_90e86b79219e438f9b7aa0892dd51da9",
  "object": "Shipment"
}

POST/shipments

One-Call Buy Shipment with Carbon Offset

Request Parameters

param	example	info
carbon_offset	true	Whether you want to buy a shipment with carbon offset.

Example

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Newtonsoft.Json;
using EasyPost;
using EasyPost.Models.API;
using EasyPost.Parameters;

namespace EasyPostExamples
{
    public class Examples
    {
        public static async Task Main()
        {
            string apiKey = Environment.GetEnvironmentVariable("EASYPOST_API_KEY")!;

            var client = new EasyPost.Client(apiKey);

            Parameters.Shipment.Create parameters = new()
            {
                ToAddress = new Parameters.Address.Create
                {
                    Name = "Dr. Steve Brule",
                    Street1 = "417 Montgomery Street",
                    Street2 = "5th Floor",
                    City = "San Francisco",
                    State = "CA",
                    Country = "US",
                    Zip = "94104"
                },
                FromAddress = new Parameters.Address.Create
                {
                    Company = "EasyPost",
                    Street1 = "417 Montgomery Street",
                    Street2 = "Floor 5",
                    City = "San Francisco",
                    State = "CA",
                    Country = "US",
                    Zip = "94104"
                },
                Parcel = new Parameters.Parcel.Create
                {
                    Length = 8,
                    Width = 6,
                    Height = 5,
                    Weight = 10
                },
                CarrierAccountIds = new List<string> { "ca_..." },
                Service = "NextDayAir",
                Reference = "ShipmentRef",
                CarbonOffset = true,
            };

            Shipment shipment = await client.Shipment.Create(parameters);

            Console.WriteLine(JsonConvert.SerializeObject(shipment, Formatting.Indented));
        }
    }
}

{
  "created_at": "2022-10-17T17:18:04Z",
  "is_return": false,
  "messages": [],
  "mode": "test",
  "options": {
    "currency": "USD",
    "payment": {
      "type": "SENDER"
    },
    "date_advance": 0
  },
  "reference": null,
  "status": "unknown",
  "tracking_code": "9405500106068143633105",
  "updated_at": "2022-10-17T17:18:05Z",
  "batch_id": null,
  "batch_status": null,
  "batch_message": null,
  "customs_info": {
    "id": "cstinfo_8adecb9fa4ca4e90adb5d960c9579fcf",
    "object": "CustomsInfo",
    "created_at": "2022-10-17T17:18:04Z",
    "updated_at": "2022-10-17T17:18:04Z",
    "contents_explanation": "",
    "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",
    "mode": "test",
    "declaration": null,
    "customs_items": [
      {
        "id": "cstitem_5f5a69a313384b13835dea9b3a7b1494",
        "object": "CustomsItem",
        "created_at": "2022-10-17T17:18:04Z",
        "updated_at": "2022-10-17T17:18:04Z",
        "description": "T-shirt",
        "hs_tariff_number": "123456",
        "origin_country": "US",
        "quantity": 1,
        "value": "10.0",
        "weight": 5.0,
        "code": "123",
        "mode": "test",
        "manufacturer": null,
        "currency": null,
        "eccn": null,
        "printed_commodity_identifier": null
      }
    ]
  },
  "from_address": {
    "id": "adr_a92c9a7a4e3f11edadb4ac1f6bc72124",
    "object": "Address",
    "created_at": "2022-10-17T17:18:04+00:00",
    "updated_at": "2022-10-17T17:18:04+00:00",
    "name": "EasyPost",
    "company": null,
    "street1": "417 Montgomery Street",
    "street2": "5th Floor",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94104",
    "country": "US",
    "phone": "4153334445",
    "email": "support@easypost.com",
    "mode": "test",
    "carrier_facility": null,
    "residential": null,
    "federal_tax_id": null,
    "state_tax_id": null,
    "verifications": {}
  },
  "insurance": null,
  "order_id": null,
  "parcel": {
    "id": "prcl_9a394d9a6af943cbb97ccc549e547326",
    "object": "Parcel",
    "created_at": "2022-10-17T17:18:04Z",
    "updated_at": "2022-10-17T17:18:04Z",
    "length": 20.2,
    "width": 10.9,
    "height": 5.0,
    "predefined_package": null,
    "weight": 65.9,
    "mode": "test"
  },
  "postage_label": {
    "object": "PostageLabel",
    "id": "pl_1071c07faffe4010a5cb060e25ac837a",
    "created_at": "2022-10-17T17:18:05Z",
    "updated_at": "2022-10-17T17:18:05Z",
    "date_advance": 0,
    "integrated_form": "none",
    "label_date": "2022-10-17T17:18:05Z",
    "label_resolution": 300,
    "label_size": "4x6",
    "label_type": "default",
    "label_file_type": "image/png",
    "label_url": "https://easypost-files.s3.us-west-2.amazonaws.com/files/postage_label/20221017/b0d07ac387e24d8db90a48416c088876.png",
    "label_pdf_url": null,
    "label_zpl_url": null,
    "label_epl2_url": null,
    "label_file": null
  },
  "rates": [
    {
      "id": "rate_f1ce8a63c0b54575b84618894cb214bb",
      "object": "Rate",
      "created_at": "2022-10-17T17:18:04Z",
      "updated_at": "2022-10-17T17:18:04Z",
      "mode": "test",
      "service": "Express",
      "carrier": "USPS",
      "rate": "44.55",
      "currency": "USD",
      "retail_rate": "51.30",
      "retail_currency": "USD",
      "list_rate": "44.55",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": null,
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "est_delivery_days": null,
      "shipment_id": "shp_15deb4bde7ad49ba9cde52f7e48c5c22",
      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac",
      "carbon_offset": {
        "object": "CarbonOffset",
        "grams": 154,
        "price": "0.11",
        "currency": "USD"
      }
    },
    {
      "id": "rate_bc13f11026f244a8924ff6e0081e5d58",
      "object": "Rate",
      "created_at": "2022-10-17T17:18:04Z",
      "updated_at": "2022-10-17T17:18:04Z",
      "mode": "test",
      "service": "Priority",
      "carrier": "USPS",
      "rate": "10.07",
      "currency": "USD",
      "retail_rate": "13.45",
      "retail_currency": "USD",
      "list_rate": "10.07",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": 2,
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "est_delivery_days": 2,
      "shipment_id": "shp_15deb4bde7ad49ba9cde52f7e48c5c22",
      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac",
      "carbon_offset": {
        "object": "CarbonOffset",
        "grams": 154,
        "price": "0.11",
        "currency": "USD"
      }
    }
  ],
  "refund_status": null,
  "scan_form": null,
  "selected_rate": {
    "id": "rate_bc13f11026f244a8924ff6e0081e5d58",
    "object": "Rate",
    "created_at": "2022-10-17T17:18:05Z",
    "updated_at": "2022-10-17T17:18:05Z",
    "mode": "test",
    "service": "Priority",
    "carrier": "USPS",
    "rate": "10.07",
    "currency": "USD",
    "retail_rate": "13.45",
    "retail_currency": "USD",
    "list_rate": "10.07",
    "list_currency": "USD",
    "billing_type": "easypost",
    "delivery_days": 2,
    "delivery_date": null,
    "delivery_date_guaranteed": false,
    "est_delivery_days": 2,
    "shipment_id": "shp_15deb4bde7ad49ba9cde52f7e48c5c22",
    "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
  },
  "tracker": {
    "id": "trk_d79bf6d00fff4da880ea4d0ac57c041f",
    "object": "Tracker",
    "mode": "test",
    "tracking_code": "9405500106068143633105",
    "status": "unknown",
    "status_detail": "unknown",
    "created_at": "2022-10-17T17:18:05Z",
    "updated_at": "2022-10-17T17:18:05Z",
    "signed_by": null,
    "weight": null,
    "est_delivery_date": null,
    "shipment_id": "shp_15deb4bde7ad49ba9cde52f7e48c5c22",
    "carrier": "USPS",
    "tracking_details": [],
    "fees": [],
    "carrier_detail": null,
    "public_url": "https://track.easypost.com/djE6dHJrX2Q3OWJmNmQwMGZmZjRkYTg4MGVhNGQwYWM1N2MwNDFm"
  },
  "to_address": {
    "id": "adr_a9297b274e3f11ed82f5ac1f6bc7bdc6",
    "object": "Address",
    "created_at": "2022-10-17T17:18:04+00:00",
    "updated_at": "2022-10-17T17:18:05+00:00",
    "name": "DR. STEVE BRULE",
    "company": null,
    "street1": "179 N HARBOR DR",
    "street2": null,
    "city": "REDONDO BEACH",
    "state": "CA",
    "zip": "90277-2506",
    "country": "US",
    "phone": "8573875756",
    "email": "DR_STEVE_BRULE@GMAIL.COM",
    "mode": "test",
    "carrier_facility": null,
    "residential": false,
    "federal_tax_id": null,
    "state_tax_id": null,
    "verifications": {
      "zip4": {
        "success": true,
        "errors": [],
        "details": null
      },
      "delivery": {
        "success": true,
        "errors": [],
        "details": {
          "latitude": 33.8436,
          "longitude": -118.39177,
          "time_zone": "America/Los_Angeles"
        }
      }
    }
  },
  "usps_zone": 4,
  "return_address": {
    "id": "adr_a92c9a7a4e3f11edadb4ac1f6bc72124",
    "object": "Address",
    "created_at": "2022-10-17T17:18:04+00:00",
    "updated_at": "2022-10-17T17:18:04+00:00",
    "name": "EasyPost",
    "company": null,
    "street1": "417 Montgomery Street",
    "street2": "5th Floor",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94104",
    "country": "US",
    "phone": "4153334445",
    "email": "support@easypost.com",
    "mode": "test",
    "carrier_facility": null,
    "residential": null,
    "federal_tax_id": null,
    "state_tax_id": null,
    "verifications": {}
  },
  "buyer_address": {
    "id": "adr_a9297b274e3f11ed82f5ac1f6bc7bdc6",
    "object": "Address",
    "created_at": "2022-10-17T17:18:04+00:00",
    "updated_at": "2022-10-17T17:18:05+00:00",
    "name": "DR. STEVE BRULE",
    "company": null,
    "street1": "179 N HARBOR DR",
    "street2": null,
    "city": "REDONDO BEACH",
    "state": "CA",
    "zip": "90277-2506",
    "country": "US",
    "phone": "8573875756",
    "email": "DR_STEVE_BRULE@GMAIL.COM",
    "mode": "test",
    "carrier_facility": null,
    "residential": false,
    "federal_tax_id": null,
    "state_tax_id": null,
    "verifications": {
      "zip4": {
        "success": true,
        "errors": [],
        "details": null
      },
      "delivery": {
        "success": true,
        "errors": [],
        "details": {
          "latitude": 33.8436,
          "longitude": -118.39177,
          "time_zone": "America/Los_Angeles"
        }
      }
    }
  },
  "forms": [],
  "fees": [
    {
      "object": "Fee",
      "type": "LabelFee",
      "amount": "0.00000",
      "charged": true,
      "refunded": false
    },
    {
      "object": "Fee",
      "type": "PostageFee",
      "amount": "10.07000",
      "charged": true,
      "refunded": false
    },
    {
      "object": "Fee",
      "type": "CarbonOffsetFee",
      "amount": "0.11000",
      "charged": true,
      "refunded": false
    }
  ],
  "id": "shp_15deb4bde7ad49ba9cde52f7e48c5c22",
  "object": "Shipment"
}

Forms

After a Shipment is created, you can create various associated Form objects for that Shipment such as a return packing slip, QR codes, and other international shipping forms. For more information about how to use Forms with your Shipments, please check our Forms guide.

Forms that may be returned with Shipment objects depending on the carrier and data passed:

cn22
cod_return_label
commercial_invoice
high_value_report
nafta_certificate_of_origin
order_summary

Forms that can be created after a Shipment has been bought:

commercial_invoice
label_qr_code
return_packing_slip
rma_qr_code

Form Object

attribute	type	specification
id	string	Unique, begins with "form_"
object	string	"Form"
mode	string	"test" or "production"
form_type	string	The type of form, can be one of "cn22", "cod_return_label", "commercial_invoice", "high_value_report", "label_qr_code", "nafta_certificate_of_origin", "order_summary", "return_packing_slip", "rma_qr_code"
form_url	string	The URL that a form can be downloaded from
submitted_electronically	boolean	If we have submitted the form to the carrier on behalf of the user
created_at	datetime	When the form was created
updated_at	datetime	When the form was updated

POST/shipments/:id/forms

Create Form

Please see Form guide for request parameter.

Example

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Newtonsoft.Json;
using EasyPost;
using EasyPost.Models.API;
using EasyPost.Parameters;

namespace EasyPostExamples
{
    public class Examples
    {
        public static async Task Main()
        {
            string apiKey = Environment.GetEnvironmentVariable("EASYPOST_API_KEY")!;

            var client = new EasyPost.Client(apiKey);

            // Shipment has to be purchased before forms can be generated
            Shipment shipment = await client.Shipment.Retrieve("shp_...");

            Parameters.Shipment.GenerateForm parameters = new()
            {
                Type = "return_packing_slip",
                Data = new()
                {
                    { "barcode", "RMA12345678900" },
                    {
                        "line_items", new List<Dictionary<string, object>>()
                        {
                            {
                                new Dictionary<string, object>
                                {
                                    { "title", "Square Reader" },
                                    { "barcode", "855658003251" }
                                }
                            }
                        }
                    },
                    { "units", 8 }
                }
            };

            shipment = await client.Shipment.GenerateForm(shipment.Id, parameters);

            Console.WriteLine(JsonConvert.SerializeObject(shipment, Formatting.Indented));
        }
    }
}

{
  "created_at": "2022-10-17T17:17:57Z",
  "is_return": false,
  "messages": [],
  "mode": "test",
  "options": {
    "currency": "USD",
    "payment": {
      "type": "SENDER"
    },
    "date_advance": 0
  },
  "reference": null,
  "status": "unknown",
  "tracking_code": "9405500106068143633075",
  "updated_at": "2022-10-17T17:17:58Z",
  "batch_id": null,
  "batch_status": null,
  "batch_message": null,
  "customs_info": {
    "id": "cstinfo_381a27daba534502889be3acd5589e68",
    "object": "CustomsInfo",
    "created_at": "2022-10-17T17:17:57Z",
    "updated_at": "2022-10-17T17:17:57Z",
    "contents_explanation": "",
    "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",
    "mode": "test",
    "declaration": null,
    "customs_items": [
      {
        "id": "cstitem_01bdeca5ba3d4057bce062cbe9eac7e5",
        "object": "CustomsItem",
        "created_at": "2022-10-17T17:17:57Z",
        "updated_at": "2022-10-17T17:17:57Z",
        "description": "T-shirt",
        "hs_tariff_number": "123456",
        "origin_country": "US",
        "quantity": 1,
        "value": "10.0",
        "weight": 5.0,
        "code": "123",
        "mode": "test",
        "manufacturer": null,
        "currency": null,
        "eccn": null,
        "printed_commodity_identifier": null
      }
    ]
  },
  "from_address": {
    "id": "adr_a525bec24e3f11ed8908ac1f6b0a0d1e",
    "object": "Address",
    "created_at": "2022-10-17T17:17:57+00:00",
    "updated_at": "2022-10-17T17:17:57+00:00",
    "name": "EasyPost",
    "company": null,
    "street1": "417 Montgomery Street",
    "street2": "5th Floor",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94104",
    "country": "US",
    "phone": "4153334445",
    "email": "support@easypost.com",
    "mode": "test",
    "carrier_facility": null,
    "residential": null,
    "federal_tax_id": null,
    "state_tax_id": null,
    "verifications": {}
  },
  "insurance": null,
  "order_id": null,
  "parcel": {
    "id": "prcl_4d110a16daf04c09ba4d8b0a52e74e9e",
    "object": "Parcel",
    "created_at": "2022-10-17T17:17:57Z",
    "updated_at": "2022-10-17T17:17:57Z",
    "length": 20.2,
    "width": 10.9,
    "height": 5.0,
    "predefined_package": null,
    "weight": 65.9,
    "mode": "test"
  },
  "postage_label": {
    "object": "PostageLabel",
    "id": "pl_bed6e3f2e31447829e082b9d2b3c9c14",
    "created_at": "2022-10-17T17:17:58Z",
    "updated_at": "2022-10-17T17:17:58Z",
    "date_advance": 0,
    "integrated_form": "none",
    "label_date": "2022-10-17T17:17:58Z",
    "label_resolution": 300,
    "label_size": "4x6",
    "label_type": "default",
    "label_file_type": "image/png",
    "label_url": "https://easypost-files.s3.us-west-2.amazonaws.com/files/postage_label/20221017/8a47d9778c1047eb82d009dfeddb72e1.png",
    "label_pdf_url": null,
    "label_zpl_url": null,
    "label_epl2_url": null,
    "label_file": null
  },
  "rates": [
    {
      "id": "rate_5e25b0cdcea64e00b2c48a5d51d0f78d",
      "object": "Rate",
      "created_at": "2022-10-17T17:17:58Z",
      "updated_at": "2022-10-17T17:17:58Z",
      "mode": "test",
      "service": "Express",
      "carrier": "USPS",
      "rate": "44.55",
      "currency": "USD",
      "retail_rate": "51.30",
      "retail_currency": "USD",
      "list_rate": "44.55",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": null,
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "est_delivery_days": null,
      "shipment_id": "shp_d552fce238914554944a7432d3b7c662",
      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
    },
    {
      "id": "rate_34003fbd76c148beaac91b51984ef7ef",
      "object": "Rate",
      "created_at": "2022-10-17T17:17:58Z",
      "updated_at": "2022-10-17T17:17:58Z",
      "mode": "test",
      "service": "Priority",
      "carrier": "USPS",
      "rate": "10.07",
      "currency": "USD",
      "retail_rate": "13.45",
      "retail_currency": "USD",
      "list_rate": "10.07",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": 2,
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "est_delivery_days": 2,
      "shipment_id": "shp_d552fce238914554944a7432d3b7c662",
      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
    }
  ],
  "refund_status": null,
  "scan_form": null,
  "selected_rate": {
    "id": "rate_34003fbd76c148beaac91b51984ef7ef",
    "object": "Rate",
    "created_at": "2022-10-17T17:17:58Z",
    "updated_at": "2022-10-17T17:17:58Z",
    "mode": "test",
    "service": "Priority",
    "carrier": "USPS",
    "rate": "10.07",
    "currency": "USD",
    "retail_rate": "13.45",
    "retail_currency": "USD",
    "list_rate": "10.07",
    "list_currency": "USD",
    "billing_type": "easypost",
    "delivery_days": 2,
    "delivery_date": null,
    "delivery_date_guaranteed": false,
    "est_delivery_days": 2,
    "shipment_id": "shp_d552fce238914554944a7432d3b7c662",
    "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
  },
  "tracker": {
    "id": "trk_797b64e929774dbc83369cbd033888c3",
    "object": "Tracker",
    "mode": "test",
    "tracking_code": "9405500106068143633075",
    "status": "pre_transit",
    "status_detail": "status_update",
    "created_at": "2022-10-17T17:17:58Z",
    "updated_at": "2022-10-17T17:17:58Z",
    "signed_by": null,
    "weight": null,
    "est_delivery_date": "2022-10-17T17:17:58Z",
    "shipment_id": "shp_d552fce238914554944a7432d3b7c662",
    "carrier": "USPS",
    "tracking_details": [
      {
        "object": "TrackingDetail",
        "message": "Pre-Shipment Info Sent to USPS",
        "description": null,
        "status": "pre_transit",
        "status_detail": "status_update",
        "datetime": "2022-09-17T17:17:58Z",
        "source": "USPS",
        "carrier_code": null,
        "tracking_location": {
          "object": "TrackingLocation",
          "city": null,
          "state": null,
          "country": null,
          "zip": null
        }
      },
      {
        "object": "TrackingDetail",
        "message": "Shipping Label Created",
        "description": null,
        "status": "pre_transit",
        "status_detail": "status_update",
        "datetime": "2022-09-18T05:54:58Z",
        "source": "USPS",
        "carrier_code": null,
        "tracking_location": {
          "object": "TrackingLocation",
          "city": "HOUSTON",
          "state": "TX",
          "country": null,
          "zip": "77063"
        }
      }
    ],
    "fees": [],
    "carrier_detail": {
      "object": "CarrierDetail",
      "service": "First-Class Package Service",
      "container_type": null,
      "est_delivery_date_local": null,
      "est_delivery_time_local": null,
      "origin_location": "HOUSTON TX, 77001",
      "origin_tracking_location": {
        "object": "TrackingLocation",
        "city": "HOUSTON",
        "state": "TX",
        "country": null,
        "zip": "77063"
      },
      "destination_location": "CHARLESTON SC, 29401",
      "destination_tracking_location": null,
      "guaranteed_delivery_date": null,
      "alternate_identifier": null,
      "initial_delivery_attempt": null
    },
    "public_url": "https://track.easypost.com/djE6dHJrXzc5N2I2NGU5Mjk3NzRkYmM4MzM2OWNiZDAzMzg4OGMz"
  },
  "to_address": {
    "id": "adr_a5240b3e4e3f11edbe9fac1f6bc7b362",
    "object": "Address",
    "created_at": "2022-10-17T17:17:57+00:00",
    "updated_at": "2022-10-17T17:17:58+00:00",
    "name": "DR. STEVE BRULE",
    "company": null,
    "street1": "179 N HARBOR DR",
    "street2": null,
    "city": "REDONDO BEACH",
    "state": "CA",
    "zip": "90277-2506",
    "country": "US",
    "phone": "8573875756",
    "email": "DR_STEVE_BRULE@GMAIL.COM",
    "mode": "test",
    "carrier_facility": null,
    "residential": false,
    "federal_tax_id": null,
    "state_tax_id": null,
    "verifications": {
      "zip4": {
        "success": true,
        "errors": [],
        "details": null
      },
      "delivery": {
        "success": true,
        "errors": [],
        "details": {
          "latitude": 33.8436,
          "longitude": -118.39177,
          "time_zone": "America/Los_Angeles"
        }
      }
    }
  },
  "usps_zone": 4,
  "return_address": {
    "id": "adr_a525bec24e3f11ed8908ac1f6b0a0d1e",
    "object": "Address",
    "created_at": "2022-10-17T17:17:57+00:00",
    "updated_at": "2022-10-17T17:17:57+00:00",
    "name": "EasyPost",
    "company": null,
    "street1": "417 Montgomery Street",
    "street2": "5th Floor",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94104",
    "country": "US",
    "phone": "4153334445",
    "email": "support@easypost.com",
    "mode": "test",
    "carrier_facility": null,
    "residential": null,
    "federal_tax_id": null,
    "state_tax_id": null,
    "verifications": {}
  },
  "buyer_address": {
    "id": "adr_a5240b3e4e3f11edbe9fac1f6bc7b362",
    "object": "Address",
    "created_at": "2022-10-17T17:17:57+00:00",
    "updated_at": "2022-10-17T17:17:58+00:00",
    "name": "DR. STEVE BRULE",
    "company": null,
    "street1": "179 N HARBOR DR",
    "street2": null,
    "city": "REDONDO BEACH",
    "state": "CA",
    "zip": "90277-2506",
    "country": "US",
    "phone": "8573875756",
    "email": "DR_STEVE_BRULE@GMAIL.COM",
    "mode": "test",
    "carrier_facility": null,
    "residential": false,
    "federal_tax_id": null,
    "state_tax_id": null,
    "verifications": {
      "zip4": {
        "success": true,
        "errors": [],
        "details": null
      },
      "delivery": {
        "success": true,
        "errors": [],
        "details": {
          "latitude": 33.8436,
          "longitude": -118.39177,
          "time_zone": "America/Los_Angeles"
        }
      }
    }
  },
  "forms": [
    {
      "object": "Form",
      "id": "form_7c2a0231740e457887e6a6b893967250",
      "created_at": "2022-10-17T17:18:00Z",
      "updated_at": "2022-10-17T17:18:00Z",
      "mode": "test",
      "form_type": "return_packing_slip",
      "form_url": "https://easypost-files.s3-us-west-2.amazonaws.com/files/form/20221017/ae040a1c44144ef197119771de234b54.pdf",
      "submitted_electronically": null
    }
  ],
  "fees": [
    {
      "object": "Fee",
      "type": "LabelFee",
      "amount": "0.00000",
      "charged": true,
      "refunded": false
    },
    {
      "object": "Fee",
      "type": "PostageFee",
      "amount": "10.07000",
      "charged": true,
      "refunded": false
    }
  ],
  "id": "shp_d552fce238914554944a7432d3b7c662",
  "object": "Shipment"
}

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	*This field is deprecated. Use the 'payment' option object instead.
bill_receiver_postal_code	string	*This field is deprecated. Use the 'payment' option object instead.
bill_third_party_account	string	*This field is deprecated. Use the 'payment' option object instead.
bill_third_party_country	string	*This field is deprecated. Use the 'payment' option object instead.
bill_third_party_postal_code	string	*This field is deprecated. Use the 'payment' option object instead.
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 by Carriers who support this option. Alternatively, see Carbon Offset which is provided by EasyPost and works with all Carriers.
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"
cod_address_id	string	The ID of the Address to which the COD payment should be returned. Defaults to the origin address. Only available on FedEx shipments.
content_description	string	A description of the content of the shipment.
currency	string	Which currency this shipment will show for rates if carrier allows.
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. "NO_SIGNATURE" is equivalent to releasing liability. Some options may be limited for international shipments. Carrier specific delivery confirmation options are listed below: FedEx - additional options "DIRECT" - Requires the signature of someone at the delivery address. "INDIRECT_SIGNATURE" - Requires the signature of someone at the delivery address or from somebody nearby, such as a neighbor. "SERVICE_DEFAULT" - Attempts to set the signature requirements based on the shipment details and service level. USPS - additional options "ADULT_SIGNATURE_RESTRICTED" - Requires the signature of the specific addressee, or authorized agent, who is 21 years of age or older. "SIGNATURE_RESTRICTED" - Requires the signature of the specified addressee, or authorized agent. Canada Post - "DO_NOT_SAFE_DROP" - Tells the carrier to not hide the package ("safe drop"). GSO - "STANDARD_SIGNATURE". DHL Express - option mapping SIGNATURE" - DHL Express Direct Signature NO_SIGNATURE" - DHL Express Signature Release
delivery_min_datetime	string	The earliest a package should be delivered. Supported carriers vary.
delivery_max_datetime	string	The latest a package should be delivered. Supported carriers vary.
dropoff_type	string	Method the customer will use to transfer the package to the carrier. Supported dropoff types and their corresponding carrier dropoff codes are below: FedEx REGULAR_PICKUP" - Customer to transfer package during regular pickup (default) SCHEDULED_PICKUP" - Customer to transfer package during scheduled pickup RETAIL_LOCATION" - Customer to transfer package at FedEx retail location STATION" - "STATION DROP_BOX" - Customer to use carrier drop box for package transfer
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	boolean	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
duty_payment	object	Setting duty_payment type to bill the correct account for purchasing postage. This option is only available with FedEx and UPS. type - (string) Supported values are "THIRD_PARTY", and "RECEIVER". account - (string) Setting account number. country - (string) Setting country code that the account is based in. postal_code - (string) Setting postal code that the account is based in.
endorsement	string	Supported by USPS: ELECTRONIC_SERVICE_REQUESTED TEMP_RETURN_SERVICE_REQUESTED Supported by UPS, FedEx, and DHL: NO_RETURN_TO_SENDER Supported by: USPS, UPS, FedEx, and DHL: ADDRESS_SERVICE_REQUESTED CHANGE_SERVICE_REQUESTED FORWARDING_SERVICE_REQUESTED LEAVE_IF_NO_RESPONSE RETURN_SERVICE_REQUESTED
end_shipper_id	string	Specify the responsible EndShipper for the shipment by passing in an EndShipper ID.
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	Used to identify the type of hazardous materials (HazMat) or dangerous goods being shipped. Unidentified HazMat can introduce risk to human safety, property and expose the shipper to civil penalties, especially for packages that travel via air. Each carrier may have a different way of identifying HazMat and rates will only be retuned for carriers that support the type designated. Refer to carrier documentation to determine how to identify HazMat types and for complete rules and regulations. FedEx and DHL eCommerce PRIMARY_CONTAINED: Primary Contained PRIMARY_PACKED: Primary Packed PRIMARY: Primary SECONDARY_CONTAINED: Secondary Contained SECONDARY_PACKED: Secondary Packed SECONDARY: Secondary ORMD: Other Regulated Materials—Domestic LITHIUM: Lithium FedEx, DHL eCommerce, and USPS LIMITED_QUANTITY: Limited Quantity Ground Package USPS: See EasyPost's USPS HazMat Guide and USPS Pub. 52 for complete regulations. AIR_ELIGIBLE_ETHANOL: Air Eligible Ethanol Package CLASS_1: Class 1 - Toy Propellant/Safety Fuse Package CLASS_3: Class 3 - Package CLASS_7: Class 7 - Radioactive Materials Package CLASS_8_CORROSIVE: Class 8 - Corrosive Materials Package CLASS_8_WET_BATTERY: Class 8 - Nonspillable Wet Battery Package CLASS_9_NEW_LITHIUM_INDIVIDUAL: Class 9 - Lithium Battery Marked - Ground Only Package CLASS_9_USED_LITHIUM: Class 9 - Lithium Battery - Returns Package CLASS_9_NEW_LITHIUM_DEVICE: Class 9 - Lithium batteries, marked package CLASS_9_DRY_ICE: Class 9 - Dry Ice Package CLASS_9_UNMARKED_LITHIUM: Class 9 - Lithium batteries, unmarked package CLASS_9_MAGNETIZED: Class 9 - Magnetized Materials Package DIVISION_4_1: Division 4.1 - Mailable flammable solids and Safety Matches Package DIVISION_5_1: Division 5.1 - Oxidizers Package DIVISION_5_2: Division 5.2 - Organic Peroxides Package DIVISION_6_1: Division 6.1 - Toxic Materials Package (with an LD50 of 50 mg/kg or less) DIVISION_6_2: Division 6.2 EXCEPTED_QUANTITY_PROVISION: Excepted Quantity Provision Package GROUND_ONLY: Ground Only ID8000: ID8000 Consumer Commodity Package LIGHTERS: Lighters Package SMALL_QUANTITY_PROVISION: Small Quantity Provision Package
hold_for_pickup	boolean	Package will wait at carrier facility for pickup.
incoterm	string	Incoterm negotiated for shipment. Supported values are "EXW", "FCA", "CPT", "CIP", "DAT", "DAP", "DDP", "FAS", "FOB", "CFR", and "CIF". Setting this value to anything other than "DDP" will pass the cost and responsibility of duties on to the recipient of the package(s), as specified by Incoterms rules
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. EasyPost stores all dates as UTC time.
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.
payment	object	Setting payment type to bill the correct account for purchasing postage. THIRD_PARTY is only supported on passthrough billed carriers. type - (string) Supported values are "SENDER", "THIRD_PARTY", "RECEIVER", "COLLECT". Defaults to SENDER. account - (string) Setting account number. Required for RECEIVER and THIRD_PARTY. country - (string) Setting country code that the account is based in. Required for THIRD_PARTY. postal_code - (string) Setting postal code that the account is based in. Required for RECEIVER and THIRD_PARTY.
pickup_min_datetime	string	The earliest a package should be picked up. Supported carriers vary.
pickup_max_datetime	string	The latest a package should be picked up. Supported carriers vary.
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.
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` to make your shipment eligible for Saturday delivery.
special_rates_eligibility	string	This option allows you to request the following USPS mail classes: Media Mail and Library Mail. Set to 'USPS.MEDIAMAIL' or 'USPS.LIBRARYMAIL' respectively to return those rates. These mail classes have restrictions that must be followed. See the DMM for eligibility rules.
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 FedEx Ground Economy packages onto a manifest for each trailer.
billing_ref	string	A reference ID for aggregating DHL eCommerce billing data.
certified_mail	boolean	Certified Mail provides the sender with a mailing receipt and, upon request, electronic verification that an article was delivered or that a delivery attempt was made.
registered_mail	boolean	Registered Mail is the most secure service that the USPS offers. It incorporates a system of receipts to monitor the movement of the mail from the point of acceptance to delivery
registered_mail_amount	double	The value of the package contents
return_receipt	boolean	An electronic return receipt may be purchased at the time of mailing and provides a shipper with evidence of delivery (to whom the mail was delivered and date of delivery), and information about the recipient's actual delivery address. Only applies to the USPS.

POST/shipments

Create a Shipment with Options

Any number of options can be specified during Shipment creation.

Example

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Newtonsoft.Json;
using EasyPost;
using EasyPost.Models.API;
using EasyPost.Parameters;

namespace EasyPostExamples
{
    public class Examples
    {
        public static async Task Main()
        {
            string apiKey = Environment.GetEnvironmentVariable("EASYPOST_API_KEY")!;

            var client = new EasyPost.Client(apiKey);

            Parameters.Shipment.Create parameters = new()
            {
                ToAddress = new Parameters.Address.Create
                {
                    Name = "Dr. Steve Brule",
                    Street1 = "417 Montgomery Street",
                    Street2 = "5th Floor",
                    City = "San Francisco",
                    State = "CA",
                    Country = "US",
                    Zip = "94104"
                },
                FromAddress = new Parameters.Address.Create
                {
                    Company = "EasyPost",
                    Street1 = "417 Montgomery Street",
                    Street2 = "Floor 5",
                    City = "San Francisco",
                    State = "CA",
                    Country = "US",
                    Zip = "94104"
                },
                Parcel = new Parameters.Parcel.Create
                {
                    Length = 20.2,
                    Width = 10.9,
                    Height = 5,
                    Weight = 65.9
                },
                Options = new Options
                {
                    PrintCustom1 = "Custom label message"
                }
            };

            Shipment shipment = await client.Shipment.Create(parameters);

            Console.WriteLine(JsonConvert.SerializeObject(shipment, Formatting.Indented));
        }
    }
}

{
  "created_at": "2022-10-17T17:18:10Z",
  "is_return": false,
  "messages": [],
  "mode": "test",
  "options": {
    "print_custom_1": "Custom label message",
    "currency": "USD",
    "print_custom": [
      {
        "value": "Custom label message"
      }
    ],
    "payment": {
      "type": "SENDER"
    },
    "date_advance": 0
  },
  "reference": null,
  "status": "unknown",
  "tracking_code": null,
  "updated_at": "2022-10-17T17:18:10Z",
  "batch_id": null,
  "batch_status": null,
  "batch_message": null,
  "customs_info": {
    "id": "cstinfo_455727877713441eae37d0cf3e49b078",
    "object": "CustomsInfo",
    "created_at": "2022-10-17T17:18:10Z",
    "updated_at": "2022-10-17T17:18:10Z",
    "contents_explanation": "",
    "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",
    "mode": "test",
    "declaration": null,
    "customs_items": [
      {
        "id": "cstitem_748a5250e6a043dd9fa49719d3378062",
        "object": "CustomsItem",
        "created_at": "2022-10-17T17:18:10Z",
        "updated_at": "2022-10-17T17:18:10Z",
        "description": "T-shirt",
        "hs_tariff_number": "123456",
        "origin_country": "US",
        "quantity": 1,
        "value": "10.0",
        "weight": 5.0,
        "code": "123",
        "mode": "test",
        "manufacturer": null,
        "currency": null,
        "eccn": null,
        "printed_commodity_identifier": null
      }
    ]
  },
  "from_address": {
    "id": "adr_acae73684e3f11ed83acac1f6bc7bdc6",
    "object": "Address",
    "created_at": "2022-10-17T17:18:10+00:00",
    "updated_at": "2022-10-17T17:18:10+00:00",
    "name": "EasyPost",
    "company": null,
    "street1": "417 Montgomery Street",
    "street2": "5th Floor",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94104",
    "country": "US",
    "phone": "4153334445",
    "email": "support@easypost.com",
    "mode": "test",
    "carrier_facility": null,
    "residential": null,
    "federal_tax_id": null,
    "state_tax_id": null,
    "verifications": {}
  },
  "insurance": null,
  "order_id": null,
  "parcel": {
    "id": "prcl_1bbb7ebc269f4f1f815ba3abb0381d89",
    "object": "Parcel",
    "created_at": "2022-10-17T17:18:10Z",
    "updated_at": "2022-10-17T17:18:10Z",
    "length": 20.2,
    "width": 10.9,
    "height": 5.0,
    "predefined_package": null,
    "weight": 65.9,
    "mode": "test"
  },
  "postage_label": null,
  "rates": [
    {
      "id": "rate_75183f00ed5048379b293997cab050e4",
      "object": "Rate",
      "created_at": "2022-10-17T17:18:10Z",
      "updated_at": "2022-10-17T17:18:10Z",
      "mode": "test",
      "service": "Priority",
      "carrier": "USPS",
      "rate": "10.07",
      "currency": "USD",
      "retail_rate": "13.45",
      "retail_currency": "USD",
      "list_rate": "10.07",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": 2,
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "est_delivery_days": 2,
      "shipment_id": "shp_c40aadc091ac456a8d611bb978aaa323",
      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
    },
    {
      "id": "rate_595855c1c20b4675ac0dd3ad6fa6b9bc",
      "object": "Rate",
      "created_at": "2022-10-17T17:18:10Z",
      "updated_at": "2022-10-17T17:18:10Z",
      "mode": "test",
      "service": "Express",
      "carrier": "USPS",
      "rate": "44.55",
      "currency": "USD",
      "retail_rate": "51.30",
      "retail_currency": "USD",
      "list_rate": "44.55",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": null,
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "est_delivery_days": null,
      "shipment_id": "shp_c40aadc091ac456a8d611bb978aaa323",
      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
    }
  ],
  "refund_status": null,
  "scan_form": null,
  "selected_rate": null,
  "tracker": null,
  "to_address": {
    "id": "adr_acabfe634e3f11edaee3ac1f6bc72124",
    "object": "Address",
    "created_at": "2022-10-17T17:18:10+00:00",
    "updated_at": "2022-10-17T17:18:10+00:00",
    "name": "Dr. Steve Brule",
    "company": null,
    "street1": "179 N Harbor Dr",
    "street2": null,
    "city": "Redondo Beach",
    "state": "CA",
    "zip": "90277",
    "country": "US",
    "phone": "8573875756",
    "email": "dr_steve_brule@gmail.com",
    "mode": "test",
    "carrier_facility": null,
    "residential": null,
    "federal_tax_id": null,
    "state_tax_id": null,
    "verifications": {}
  },
  "usps_zone": 4,
  "return_address": {
    "id": "adr_acae73684e3f11ed83acac1f6bc7bdc6",
    "object": "Address",
    "created_at": "2022-10-17T17:18:10+00:00",
    "updated_at": "2022-10-17T17:18:10+00:00",
    "name": "EasyPost",
    "company": null,
    "street1": "417 Montgomery Street",
    "street2": "5th Floor",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94104",
    "country": "US",
    "phone": "4153334445",
    "email": "support@easypost.com",
    "mode": "test",
    "carrier_facility": null,
    "residential": null,
    "federal_tax_id": null,
    "state_tax_id": null,
    "verifications": {}
  },
  "buyer_address": {
    "id": "adr_acabfe634e3f11edaee3ac1f6bc72124",
    "object": "Address",
    "created_at": "2022-10-17T17:18:10+00:00",
    "updated_at": "2022-10-17T17:18:10+00:00",
    "name": "Dr. Steve Brule",
    "company": null,
    "street1": "179 N Harbor Dr",
    "street2": null,
    "city": "Redondo Beach",
    "state": "CA",
    "zip": "90277",
    "country": "US",
    "phone": "8573875756",
    "email": "dr_steve_brule@gmail.com",
    "mode": "test",
    "carrier_facility": null,
    "residential": null,
    "federal_tax_id": null,
    "state_tax_id": null,
    "verifications": {}
  },
  "forms": [],
  "fees": [],
  "id": "shp_c40aadc091ac456a8d611bb978aaa323",
  "object": "Shipment"
}

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.

Rates 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	integer	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.
billing_type	string	Billing type of the rate
carbon_offset	CarbonOffset	the associated CarbonOffset object, if requested
created_at	datetime
updated_at	datetime

Service Levels

UPS Rates
USPS Rates
FedEx Rates
UPS Labels
USPS Labels
FedEx Labels
UPS Tracking
USPS Tracking
FedEx Tracking

parcelConnectBookService
parcelConnectExpeditedDDP
parcelConnectExpeditedDDU
parcelConnectPriorityDDP
parcelConnectPriorityDDPDelcon
parcelConnectPriorityDDU
parcelConnectPriorityDDUDelcon
parcelConnectPriorityDDUPQW
parcelConnectStandardDDU
parcelConnectStandardDDUPQW
parcelConnectPacketDDU

ADS
AirFreightInbound
AirFreightOutbound
AsendiaDomesticBoundPrinterMatterExpedited
AsendiaDomesticBoundPrinterMatterGround
AsendiaDomesticFlatsExpedited
AsendiaDomesticFlatsGround
AsendiaDomesticParcelGroundOver1lb
AsendiaDomesticParcelGroundUnder1lb
AsendiaDomesticParcelMAXOver1lb
AsendiaDomesticParcelMAXUnder1lb
AsendiaDomesticParcelOver1lbExpedited
AsendiaDomesticParcelUnder1lbExpedited
AsendiaDomesticPromoParcelExpedited
AsendiaDomesticPromoParcelGround
BulkFreight
BusinessMailCanadaLettermail
BusinessMailCanadaLettermailMachineable
BusinessMailEconomy
BusinessMailEconomyLPWholesale
BusinessMailEconomySPWholesale
BusinessMailIPA
BusinessMailISAL
BusinessMailPriority
BusinessMailPriorityLPWholesale
BusinessMailPrioritySPWholesale
MarketingMailCanadaPersonalizedLCP
MarketingMailCanadaPersonalizedMachineable
MarketingMailCanadaPersonalizedNDG
MarketingMailEconomy
MarketingMailIPA
MarketingMailISAL
MarketingMailPriority
PublicationsCanadaLCP
PublicationsCanadaNDG
PublicationsEconomy
PublicationsIPA
PublicationsISAL
PublicationsPriority
ePAQElite
ePAQEliteCustom
ePAQEliteDAP
ePAQEliteDDP
ePAQEliteDDPOversized
ePAQEliteDPD
ePAQEliteDirectAccessCanadaDDP
ePAQEliteOversized
ePAQPlus
ePAQPlusCustom
ePAQPlusCustomsPrepaid
ePAQPlusDAP
ePAQPlusDDP
ePAQPlusEconomy
ePAQPlusWholesale
ePAQPlusePacket
ePAQPlusePacketCanadaCustomsPrePaid
ePAQPlusePacketCanadaDDP
ePAQReturnsDomestic
ePAQReturnsInternational
ePAQSelect
ePAQSelectCustom
ePAQSelectCustomsPrepaidByShopper
ePAQSelectDAP
ePAQSelectDDP
ePAQSelectDDPDirectAccess
ePAQSelectDirectAccess
ePAQSelectDirectAccessCanadaDDP
ePAQSelectEconomy
ePAQSelectOversized
ePAQSelectOversizedDDP
ePAQSelectPMEI
ePAQSelectPMEICanadaCustomsPrePaid
ePAQSelectPMEIPCPostage
ePAQSelectPMI
ePAQSelectPMICanadaCustomsPrepaid
ePAQSelectPMICanadaDDP
ePAQSelectPMINonPresort
ePAQSelectPMIPCPostage
ePAQStandard
ePAQStandardCustom
ePAQStandardEconomy
ePAQStandardIPA
ePAQStandardISAL
ePaqSelectPMEINonPresort

ParcelPost
ExpressPost
International
Commercial

AxleHireDelivery

NEXT_DAY
EXPRESS

DeliveredTonight
RegularParcel
ExpeditedParcel
Xpresspost
XpresspostCertified
Priority
LibraryBooks
ExpeditedParcelUSA
SmallPacketUSAAir
TrackedPacketUSA
TrackedPacketUSALVM
XpresspostUSA
XpresspostInternational
InternationalParcelAir
InternationalParcelSurface
SmallPacketInternationalAir
SmallPacketInternationalSurface
TrackedPacketInternational
ExpeditedParcelPlus

Ground
USA
SelectLetter
SelectPak
Select
OvernightLetter
OvernightPak
Overnight
USALetter
USAPak
SelectUSA
International

DISTRIBUTION
Same Day

No service levels for Chronopost.

CAECOCE (US to CA Economy)
CAECONE (US to CA Economy)
CAECOWE (US to CA Economy)
ECOCE (Economy Central)
ECOEA (Economy East)
ECONE (Economy Northeast)
ECOSO (Economy South)
ECOWE (Economy West)
EUECOWE (US to Europe Economy)
EXPBNE (Expedited Northeast)
EXPWE (Expedited West)
REGCE (Regional Central)
REGEA (Regional East)
REGNE (Regional Northeast)
REGSO (Regional South)
REGWE (Regional West)

No service levels for CloudSort.

BASIC_PARCEL

RoadExpress
AggExpAtlP10
AggExpAtlP25
AggExpAtlBaseandKilo
AggExpAtlP0
AggExpAtlP1
AggExpAtlP3
AggExpAtlP5
AggDropOffHubbedBaseandKilo
AggDropOffHubbedP0
AggDropOffHubbedP1
AggDropOffHubbedP3
AggDropOffHubbedP5
AggStdAtlP10
AggStdAtlBaseandKilo
AggStdAtlP0
AggStdAtlP1
AggStdAtlP3
AggStdAtlP5
AggEcomBaseandKilo
AggEcomP0
AggEcomP1
AggEcomP3
AggEcomP5
AggDropOffHubbedP10
AggDropOffHubbedP25
AggStdAtlP25
AggEcomP10
AggEcomP25
AustralianCityExpress
DropShip500GramParcel
DropShip1KgParcel
DropShip3KgParcel
DropShip5KgParcel
DomesticPriority
DropShip10KgParcel
DropShip20KgParcel
DomesticPrioritySignature
GoldDomestic
RoadExpressNoDelivery
RoadExpressNoPickUp
500GramParcel
500GramParcelATL
10KgParcel
10KgParcelATL
15KgParcel
15KgParcelATL
1KgParcelATL
2KgParcel
25KgParcel
25KgParcelATL
2KgParcelATL
3KgParcelATL
5Kg Parcel ATL
AustralianCityExpressSignature
DomesticSaverSignature
DomesticOffPeak
DomesticSaver
DomesticOffPeakSignature
GoldDomesticSignature
1KgSatchelATL
1KgSatchel
3KgSatchel
5KgSatchel
3KgSatchelATL
5KgSatchelATL
500GramSatchelATL
500GramSatchel
5KSatchel
ExpressInternationalPriority
InternationalSaver
InternationalExpressImport
InternationalExpress
500gmParcel
1KgParcel
3KgParcel
5KgParcel

ParcelMax
InternationalEconomy
InternationalStandard
InternationalExpress
DomesticTracked

Saturday
Economy
Noon-It
Early-It
Afternoon

PacketPlus

PriorityPacketPlus
PriorityPacket
PriorityPacketTracked
BusinessMailRegistered
StandardPacket
BusinessMailStandard

DHLParcelExpedited
DHLParcelExpeditedMax
DHLParcelGround
DHLBPMExpedited
DHLBPMGround
DHLParcelInternationalDirect
DHLParcelInternationalStandard
DHLPacketInternational
DHLParcelInternationalDirectPriority
DHLParcelInternationalDirectStandard

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

EuroPaket
Paket
PaketConnect
PaketInternational
Retoure

No service levels for DHL SmartMail.

DPDCLASSIC
DPD8:30
DPD10:00
DPD12:00
DPD18:00
DPDEXPRESS
DPDPARCELLETTER
DPDPARCELLETTERPLUS
DPDINTERNATIONALMAIL

DPDNL_CLASSIC
EXPRESS_10
EXPRESS_12
EXPRESS_18
INTERNATIONAL_EXPRESS
DPDNL_HOME
DPDNL_TO_SHOP

AirClassicInternationalAir
AirExpressInternationalAir
ExpresspakDpd10:30
ExpresspakDpd12:00
ExpresspakDpdClassic
ExpresspakDpdNextDay
ExpresspakSaturday
ExpresspakSaturday10:30
ExpresspakSaturday12:00
ExpresspakSunday
ExpresspakSunday12:00
FreightParcelDpd10:30
FreightParcelDpd12:00
FreightParcelDpdClassic
FreightParcelDpdNextDay
FreightParcelDpdTwoDay
FreightParcelSaturday
FreightParcelSaturday10:30
FreightParcelSaturday12:00
FreightParcelSunday
FreightParcelSunday12:00
PalletDpd10:30
PalletDpd12:00
PalletDpdClassic
PalletDpdNextDay
PalletDpdTwoDay
PalletSaturday
PalletSaturday10:30
PalletSaturday12:00
PalletSunday
PalletSunday12:00
ParcelDpd10:30
ParcelDpd12:00
ParcelDpdClassic
ParcelDpdNextDay
ParcelDpdTwoDay
ParcelReturnToShop
ParcelSaturday
ParcelSaturday10:30
ParcelSaturday12:00
ParcelSunday
ParcelSunday12:00

CourierServiceDDP
CourierServiceDDU
DomesticEconomyParcel
DomesticParcelBPM
DomesticPriorityParcel
DomesticPriorityParcelBPM
EMIService
EconomyParcelService
IPAService
ISALService
PMIService
PriorityParcelDDP
PriorityParcelDDU
PriorityParcelDeliveryConfirmationDDP
PriorityParcelDeliveryConfirmationDDU
ePacketService

NextDayBy930
NextDayBy1130
NextDay
Ground
TwoDay
LTL

Courier2Home
Courier2HomeNextDay
Shop2Home
Shop2HomeNextDay
Shop2Shop
Shop2ShopNextDay

Parcel
Satchel

FEDEX_2_DAY
FEDEX_2_DAY_AM
FEDEX_EXPRESS_SAVER
FEDEX_GROUND
FEDEX_INTERNATIONAL_CONNECT_PLUS
FIRST_OVERNIGHT
GROUND_HOME_DELIVERY
INTERNATIONAL_ECONOMY
INTERNATIONAL_FIRST
INTERNATIONAL_PRIORITY
PRIORITY_OVERNIGHT
SMART_POST
STANDARD_OVERNIGHT

SMART_POST

No service levels for FedEx Mailview.

XParcelPriority
XParcelExpedited
XParcelReturns
XParcelGround
XParcelExpeditedPlus

Standard
Expedited

CaliforniaParcelService
EarlyPriorityOvernight
EarlySaturdayService
Ground
Overnight
PriorityOvernight
SaturdayDeliveryService

Xpress

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

No service levels for JP Post.

No service levels for Kuroneko Yamato.

No service levels for La Poste.

SameDay
NextDay
Weekend

LoomisGround
LoomisExpress1800
LoomisExpress1200
LoomisExpress900

No service levels for LSO.

Standard

ParcelSelect
ParcelSelectLightweight
Ground
Express
FirstClassMail
PriorityMail
BoundPrintedMatter

Sunrise
Gold
OnTracGround
SameDay
PalletizedFreight

NxtDay

ParcelSelectLightweight
Priority
BPM
ParcelSelect
MediaMail
MarketingParcel
MarketingParcelTracked
ParcelSelectLightweightHazardousMaterial
ParcelSelectHazardousMaterial
USPSGroundAdvantage
USPSGroundAdvantageLightweight

Pandion Express

Express9
Express9Secure
Express9CourierPack
Express10
Express10Secure
Express10Exchange
Express10SecureExchange
Express10CourierPack
ExpressAM
ExpressAMSecure
ExpressAMExchange
ExpressAMSecureExchange
ExpressAMCourierPack
ExpressPM
ExpressPMSecure
Express24
Express24Large
Express24Secure
Express24Exchange
Express24SecureExchange
Express24CourierPack
Express48
Express48Large
ParcelRiderPlus
GlobalBulkDirect
GlobalExpress
GlobalExpressEnvelopeDelivery
GlobalExpressPackDelivery
GlobalValue
GlobalPriority
GlobalPriorityReturns
EuroPriorityHome
EuroPriorityBusiness
IrelandExpress

No service levels for Passport.

No service levels for PostNL.

PurolatorExpress
PurolatorExpress12PM
PurolatorExpressPack12PM
PurolatorExpressBox12PM
PurolatorExpressEnvelope12PM
PurolatorExpress1030AM
PurolatorExpress9AM
PurolatorExpressBox
PurolatorExpressBox1030AM
PurolatorExpressBox9AM
PurolatorExpressBoxEvening
PurolatorExpressBoxInternational
PurolatorExpressBoxUS
PurolatorExpressEnvelope
PurolatorExpressEnvelope1030AM
PurolatorExpressEnvelope9AM
PurolatorExpressEnvelopeEvening
PurolatorExpressEnvelopeInternational
PurolatorExpressEnvelopeUS
PurolatorExpressEvening
PurolatorExpressInternational
PurolatorExpressInternational1030AM
PurolatorExpressInternational1200
PurolatorExpressInternational9AM
PurolatorExpressBoxInternational1030AM
PurolatorExpressBoxInternational1200
PurolatorExpressBoxInternational9AM
PurolatorExpressEnvelopeInternational1030AM
PurolatorExpressEnvelopeInternational1200
PurolatorExpressEnvelopeInternational9AM
PurolatorExpressPackInternational1030AM
PurolatorExpressPackInternational1200
PurolatorExpressPackInternational9AM
PurolatorExpressPack
PurolatorExpressPack1030AM
PurolatorExpressPack9AM
PurolatorExpressPackEvening
PurolatorExpressPackInternational
PurolatorExpressPackUS
PurolatorExpressUS
PurolatorExpressUS1030AM
PurolatorExpressUS1200
PurolatorExpressUS9AM
PurolatorExpressBoxUS1030AM
PurolatorExpressBoxUS1200
PurolatorExpressBoxUS9AM
PurolatorExpressEnvelopeUS1030AM
PurolatorExpressEnvelopeUS1200
PurolatorExpressEnvelopeUS9AM
PurolatorExpressPackUS1030AM
PurolatorExpressPackUS1200
PurolatorExpressPackUS9AM
PurolatorGround
PurolatorGround1030AM
PurolatorGround9AM
PurolatorGround12PM
PurolatorGroundDistribution
PurolatorGroundEvening
PurolatorGroundUS
PurolatorQuickShip
PurolatorQuickShipEnvelope
PurolatorQuickShipPack
PurolatorQuickShipBox

InternationalPriority
InternationalEconomy
InternationalStandard
InternationalTrackedAndSigned
InternationalTracked
InternationalSigned
AccountMail
RoyalMailUnsigned
RoyalMail
SpecialDeliveryGuaranteed
SpecialDeliveryGuaranteed1pm
SpecialDeliveryGuaranteed9am
StandardLetter
Tracked24
Tracked24HighVolume
Tracked24HighVolumeSignature
Tracked24LBT
Tracked24SignatureLBT
Tracked48LBT
Tracked48SignatureLBT
Tracked24Signature
Tracked48
Tracked48HighVolume
Tracked48HighVolumeSignature
Tracked48Signature
TrackedReturns24
TrackedReturns48
CrossBorderImportTracked48HighVolume

Ecommerce Standard Tracked
Ecommerce Express Tracked
Domestic Express
Domestic Standard

Standard
Express

InternationalStandardExpressDoc
InternationalStandardExpressParcel
InternationalEconomyExpressPilot
InternationalEconomyExpressDoc
InternationalEconomyExpressParcel
DomesticExpress
DomesticStandard
DomesticIntraCity
StandardExpress
EconomyExpress

SAMEDAY

SpeeDeeDelivery

NEXTDAY
SAMEDAY

NextDay
Return

IPEC Direct
IPEC Fashion
IPEC Local
IPEC Priority
IPEC Road Express
IPEC Sensitive
IPEC VicEXP

DeliveryService

Ground
UPSStandard
UPSSaver
Express
ExpressPlus
Expedited
NextDayAir
NextDayAirSaver
NextDayAirEarlyAM
2ndDayAir
2ndDayAirAM
3DaySelect

No service levels for UPS iParcel.

BPMFlats
BPMParcels
EconomyMailInnovations
ExpeditedMailInnovations
First
MarketingParcels
MediaMail
ParcelSelect
ParcelSelectLightweight-Irreg
Priority
PriorityMailInnovations
SingleReturns
StandardFlats

First
Priority
Express
GroundAdvantage
LibraryMail
MediaMail
FirstClassMailInternational
FirstClassPackageInternationalService
PriorityMailInternational
ExpressMailInternational

nextDay
sameDay

No service levels for Yanwen.

POST/shipments/:id/rerate

Regenerate Rates for a Shipment

You can regenerate the Rates of a Shipment at any time. This is ideal when shipments aren't bought the same day as they were created and you want the most up-to-date rates available. This operation respects the carrier_accounts attribute.

Example

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Newtonsoft.Json;
using EasyPost;
using EasyPost.Models.API;
using EasyPost.Parameters;

namespace EasyPostExamples
{
    public class Examples
    {
        public static async Task Main()
        {
            string apiKey = Environment.GetEnvironmentVariable("EASYPOST_API_KEY")!;

            var client = new EasyPost.Client(apiKey);

            Shipment shipment = await client.Shipment.Retrieve("shp_...");

            shipment = await client.Shipment.RegenerateRates(shipment.Id);

            Console.WriteLine(JsonConvert.SerializeObject(shipment, Formatting.Indented));
        }
    }
}

{
  "rates": [
    {
      "id": "rate_c17bcb97fa114275844eadf830bd50fc",
      "object": "Rate",
      "created_at": "2023-07-10T17:30:24Z",
      "updated_at": "2023-07-10T17:30:24Z",
      "mode": "test",
      "service": "Priority",
      "carrier": "USPS",
      "rate": "7.47",
      "currency": "USD",
      "retail_rate": "14.05",
      "retail_currency": "USD",
      "list_rate": "10.27",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": 2,
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "est_delivery_days": 2,
      "shipment_id": "shp_29f408c3cd5b4ab18ab811efede7f7a8",
      "carrier_account_id": "ca_b25657e9896e4d63ac8151ac346ac41e"
    },
    {
      "id": "rate_d0d34bcbfe874eb1ba9b9cc3f97e7b63",
      "object": "Rate",
      "created_at": "2023-07-10T17:30:24Z",
      "updated_at": "2023-07-10T17:30:24Z",
      "mode": "test",
      "service": "GroundAdvantage",
      "carrier": "USPS",
      "rate": "8.92",
      "currency": "USD",
      "retail_rate": "8.92",
      "retail_currency": "USD",
      "list_rate": "8.92",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": null,
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "est_delivery_days": null,
      "shipment_id": "shp_29f408c3cd5b4ab18ab811efede7f7a8",
      "carrier_account_id": "ca_b25657e9896e4d63ac8151ac346ac41e"
    },
    {
      "id": "rate_3436b225ef4746c4b532232d5e36285f",
      "object": "Rate",
      "created_at": "2023-07-10T17:30:24Z",
      "updated_at": "2023-07-10T17:30:24Z",
      "mode": "test",
      "service": "First",
      "carrier": "USPS",
      "rate": "8.92",
      "currency": "USD",
      "retail_rate": "8.92",
      "retail_currency": "USD",
      "list_rate": "8.92",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": 3,
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "est_delivery_days": 3,
      "shipment_id": "shp_29f408c3cd5b4ab18ab811efede7f7a8",
      "carrier_account_id": "ca_b25657e9896e4d63ac8151ac346ac41e"
    },
    {
      "id": "rate_9d845af5e6a34a42a3cb09de338cb833",
      "object": "Rate",
      "created_at": "2023-07-10T17:30:24Z",
      "updated_at": "2023-07-10T17:30:24Z",
      "mode": "test",
      "service": "Express",
      "carrier": "USPS",
      "rate": "46.85",
      "currency": "USD",
      "retail_rate": "54.20",
      "retail_currency": "USD",
      "list_rate": "46.85",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": null,
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "est_delivery_days": null,
      "shipment_id": "shp_29f408c3cd5b4ab18ab811efede7f7a8",
      "carrier_account_id": "ca_b25657e9896e4d63ac8151ac346ac41e"
    }
  ]
}

POST/beta/rates

Retrieve Rates for a Shipment

BETA: This feature is in Beta and subject to change. For feedback or questions, please contact Support.

You can retrieve Rates without creating a Shipment object using this endpoint. This endpoint is ideal when wanting to display or compare rates without creating Shipment objects. The Rate objects returned by this endpoint do not include IDs.

Request Parameters

param	example	info
reference	"my-reference"	An optional field that may be used in place of id in other API endpoints
to_address	<Address>	Can be specified by ID or attributes to create a new one, and be verified inline. See Create and Verify Address
from_address	<Address>	Can be specified by ID or attributes to create a new one, and be verified inline. See Create and Verify Address
parcel	<Parcel>
carrier_accounts	["ca_..."]	List of carrier accounts
service	"Priority"	The service of carrier

Example

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Newtonsoft.Json;
using EasyPost;
using EasyPost.Models.API;
using EasyPost.Parameters;

namespace EasyPostExamples
{
    public class Examples
    {
        public static async Task Main()
        {
            string apiKey = Environment.GetEnvironmentVariable("EASYPOST_API_KEY")!;

            var client = new EasyPost.Client(apiKey);

            Parameters.Beta.Rate.Retrieve shipmentDetails = new()
            {
                ToAddress = new Parameters.Address.Create
                {
                    Name = "Dr. Steve Brule",
                    Street1 = "179 N Harbor Dr",
                    City = "Redondo Beach",
                    State = "CA",
                    Zip = "90277",
                    Country = "US",
                    Phone = "8573875756",
                    Email = "dr_steve_brule@gmail.com"
                },
                FromAddress = new Parameters.Address.Create
                {
                    Name = "EasyPost",
                    Street1 = "417 Montgomery Street",
                    Street2 = "5th Floor",
                    City = "San Francisco",
                    State = "CA",
                    Zip = "94104",
                    Country = "US",
                    Phone = "4153334445",
                    Email = "support@easypost.com",
                },
                Parcel = new Parameters.Parcel.Create
                {
                    Length = 20.2,
                    Width = 10.9,
                    Height = 5,
                    Weight = 65.9
                }
            };

            List<StatelessRate> rates = await client.Beta.Rate.RetrieveStatelessRates(shipmentDetails);

            Console.WriteLine(JsonConvert.SerializeObject(rates, Formatting.Indented));
        }
    }
}

{
  "from_address": {
    "object": "Address",
    "name": "EasyPost",
    "street1": "417 Montgomery Street",
    "street2": "5th Floor",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94104",
    "country": "US",
    "phone": "4153334445",
    "email": "support@easypost.com"
  },
  "to_address": {
    "object": "Address",
    "name": "Dr. Steve Brule",
    "street1": "179 N Harbor Dr",
    "city": "Redondo Beach",
    "state": "CA",
    "zip": "90277",
    "country": "US",
    "phone": "8573875756",
    "email": "dr_steve_brule@gmail.com"
  },
  "rates": [
    {
      "object": "Rate",
      "mode": "production",
      "service": "Express",
      "carrier": "USPS",
      "rate": "44.55",
      "currency": "USD",
      "retail_rate": "51.30",
      "retail_currency": "USD",
      "list_rate": "44.55",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": null,
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "est_delivery_days": null,
      "carrier_account_id": "ca_fe6c4f1489b545d49b698d4712fd4b95"
    },
    {
      "object": "Rate",
      "mode": "production",
      "service": "Priority",
      "carrier": "USPS",
      "rate": "10.07",
      "currency": "USD",
      "retail_rate": "13.45",
      "retail_currency": "USD",
      "list_rate": "10.07",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": 2,
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "est_delivery_days": 2,
      "carrier_account_id": "ca_fe6c4f1489b545d49b698d4712fd4b95"
    },
    {
      "object": "Rate",
      "mode": "production",
      "service": "3DaySelect",
      "carrier": "UPSDAP",
      "rate": "11.38",
      "currency": "USD",
      "retail_rate": "30.21",
      "retail_currency": "USD",
      "list_rate": "31.89",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": 3,
      "delivery_date": "2022-11-28T23:00:00Z",
      "delivery_date_guaranteed": false,
      "est_delivery_days": 3,
      "carrier_account_id": "ca_8f1074ead87444788a1664b90399bc0a"
    },
    {
      "object": "Rate",
      "mode": "production",
      "service": "NextDayAirEarlyAM",
      "carrier": "UPSDAP",
      "rate": "78.35",
      "currency": "USD",
      "retail_rate": "154.49",
      "retail_currency": "USD",
      "list_rate": "161.74",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": 1,
      "delivery_date": "2022-11-23T08:00:00Z",
      "delivery_date_guaranteed": true,
      "est_delivery_days": 1,
      "carrier_account_id": "ca_8f1074ead87444788a1664b90399bc0a"
    },
    {
      "object": "Rate",
      "mode": "production",
      "service": "2ndDayAirAM",
      "carrier": "UPSDAP",
      "rate": "17.00",
      "currency": "USD",
      "retail_rate": "43.99",
      "retail_currency": "USD",
      "list_rate": "47.57",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": 2,
      "delivery_date": "2022-11-25T23:00:00Z",
      "delivery_date_guaranteed": false,
      "est_delivery_days": 2,
      "carrier_account_id": "ca_8f1074ead87444788a1664b90399bc0a"
    },
    {
      "object": "Rate",
      "mode": "production",
      "service": "Ground",
      "carrier": "UPSDAP",
      "rate": "9.25",
      "currency": "USD",
      "retail_rate": "15.05",
      "retail_currency": "USD",
      "list_rate": "16.04",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": 2,
      "delivery_date": "2022-11-25T23:00:00Z",
      "delivery_date_guaranteed": false,
      "est_delivery_days": 2,
      "carrier_account_id": "ca_8f1074ead87444788a1664b90399bc0a"
    },
    {
      "object": "Rate",
      "mode": "production",
      "service": "NextDayAirSaver",
      "carrier": "UPSDAP",
      "rate": "42.79",
      "currency": "USD",
      "retail_rate": "115.11",
      "retail_currency": "USD",
      "list_rate": "120.97",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": 1,
      "delivery_date": "2022-11-23T23:00:00Z",
      "delivery_date_guaranteed": true,
      "est_delivery_days": 1,
      "carrier_account_id": "ca_8f1074ead87444788a1664b90399bc0a"
    },
    {
      "object": "Rate",
      "mode": "production",
      "service": "NextDayAir",
      "carrier": "UPSDAP",
      "rate": "48.35",
      "currency": "USD",
      "retail_rate": "118.71",
      "retail_currency": "USD",
      "list_rate": "125.96",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": 1,
      "delivery_date": "2022-11-23T10:30:00Z",
      "delivery_date_guaranteed": true,
      "est_delivery_days": 1,
      "carrier_account_id": "ca_8f1074ead87444788a1664b90399bc0a"
    },
    {
      "object": "Rate",
      "mode": "production",
      "service": "2ndDayAir",
      "carrier": "UPSDAP",
      "rate": "15.49",
      "currency": "USD",
      "retail_rate": "39.28",
      "retail_currency": "USD",
      "list_rate": "42.92",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": 2,
      "delivery_date": "2022-11-25T23:00:00Z",
      "delivery_date_guaranteed": false,
      "est_delivery_days": 2,
      "carrier_account_id": "ca_8f1074ead87444788a1664b90399bc0a"
    }
  ],
  "options": {
    "currency": "USD",
    "payment": {
      "type": "SENDER"
    },
    "date_advance": 0
  },
  "parcel": {
    "object": "Parcel",
    "length": 20.2,
    "width": 10.9,
    "height": 5,
    "weight": 65
  },
  "messages": []
}

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
carrier_account_id	string	the account id of the carrier. Useful if you have multiple accounts with the same carrier

SmartRate

The SmartRate API provides shippers with highly accurate, Shipment-level transit time predictions which can be used to save money, improve on-time delivery, and provide end customers with reliable delivery estimates.

The SmartRate API accepts a Shipment ID and returns predicted transit days across a variety of percentiles for each carrier service being evaluated for the Shipment. The transit time predictions in the response are based off of a sophisticated model using actual historical data for the shipping lane in question.

To make a request to the SmartRate API, first create a Shipment, then make the SmartRate call. Using the response, you can now make better data-driven decisions about which Rate to select when purchasing a label.

Time in Transit Object

attribute	type	specification
percentile_50	integer	expected transit days at the 50th percentile
percentile_75	integer	expected transit days at the 75th percentile
percentile_85	integer	expected transit days at the 85th percentile
percentile_90	integer	expected transit days at the 90th percentile
percentile_95	integer	expected transit days at the 95th percentile
percentile_97	integer	expected transit days at the 97th percentile
percentile_99	integer	expected transit days at the 99th percentile

GET/shipments/:id/smartrate

Retrieve Time in Transit statistics across all Rates for a Shipment

The SmartRate API returns a Time in Transit object with transit days across a variety of percentiles for every Rate for a given Shipment. Transit days are calculated as the number of business days between the first time the carrier acknowledges possession of the Shipment and the first out-for-delivery attempt.

Example

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Newtonsoft.Json;
using EasyPost;
using EasyPost.Models.API;

namespace EasyPostExamples
{
    public class Examples
    {
        public static async Task Main()
        {
            string apiKey = Environment.GetEnvironmentVariable("EASYPOST_API_KEY")!;

            var client = new EasyPost.Client(apiKey);

            Shipment shipment = await client.Shipment.Retrieve("shp_...");

            List<SmartRate> smartRates = await client.Shipment.GetSmartRates(shipment.Id);

            Console.WriteLine(JsonConvert.SerializeObject(smartRates, Formatting.Indented));
        }
    }
}

{
  "result": [
    {
      "carrier": "USPS",
      "carrier_account_id": "ca_b25657e9896e4d63ac8151ac346ac41e",
      "created_at": "2023-07-10T17:30:41Z",
      "currency": "USD",
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "delivery_days": null,
      "est_delivery_days": null,
      "id": "rate_31f5c6b890de4c1385cd02b847115bb9",
      "list_currency": "USD",
      "list_rate": 46.85,
      "mode": "test",
      "object": "Rate",
      "rate": 46.85,
      "retail_currency": "USD",
      "retail_rate": 54.2,
      "service": "Express",
      "shipment_id": "shp_a4e5255e952c40c78bd9c548efe9f4e6",
      "time_in_transit": {
        "percentile_50": 1,
        "percentile_75": 2,
        "percentile_85": 2,
        "percentile_90": 2,
        "percentile_95": 3,
        "percentile_97": 3,
        "percentile_99": 4
      },
      "updated_at": "2023-07-10T17:30:41Z"
    },
    {
      "carrier": "USPS",
      "carrier_account_id": "ca_b25657e9896e4d63ac8151ac346ac41e",
      "created_at": "2023-07-10T17:30:41Z",
      "currency": "USD",
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "delivery_days": 2,
      "est_delivery_days": 2,
      "id": "rate_2005759def924d4cbf21eb744bd020c8",
      "list_currency": "USD",
      "list_rate": 10.27,
      "mode": "test",
      "object": "Rate",
      "rate": 7.47,
      "retail_currency": "USD",
      "retail_rate": 14.05,
      "service": "Priority",
      "shipment_id": "shp_a4e5255e952c40c78bd9c548efe9f4e6",
      "time_in_transit": {
        "percentile_50": 2,
        "percentile_75": 2,
        "percentile_85": 2,
        "percentile_90": 2,
        "percentile_95": 2,
        "percentile_97": 3,
        "percentile_99": 4
      },
      "updated_at": "2023-07-10T17:30:41Z"
    },
    {
      "carrier": "USPS",
      "carrier_account_id": "ca_b25657e9896e4d63ac8151ac346ac41e",
      "created_at": "2023-07-10T17:30:41Z",
      "currency": "USD",
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "delivery_days": null,
      "est_delivery_days": null,
      "id": "rate_e34cd1a5d9e44b72a0d4b538e98b7468",
      "list_currency": "USD",
      "list_rate": 8.92,
      "mode": "test",
      "object": "Rate",
      "rate": 8.92,
      "retail_currency": "USD",
      "retail_rate": 8.92,
      "service": "GroundAdvantage",
      "shipment_id": "shp_a4e5255e952c40c78bd9c548efe9f4e6",
      "time_in_transit": {
        "percentile_50": 2,
        "percentile_75": 2,
        "percentile_85": 2,
        "percentile_90": 2,
        "percentile_95": 2,
        "percentile_97": 3,
        "percentile_99": 4
      },
      "updated_at": "2023-07-10T17:30:41Z"
    },
    {
      "carrier": "USPS",
      "carrier_account_id": "ca_b25657e9896e4d63ac8151ac346ac41e",
      "created_at": "2023-07-10T17:30:41Z",
      "currency": "USD",
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "delivery_days": 3,
      "est_delivery_days": 3,
      "id": "rate_3049fb50b21744bcb386a0a1cd027846",
      "list_currency": "USD",
      "list_rate": 8.92,
      "mode": "test",
      "object": "Rate",
      "rate": 8.92,
      "retail_currency": "USD",
      "retail_rate": 8.92,
      "service": "First",
      "shipment_id": "shp_a4e5255e952c40c78bd9c548efe9f4e6",
      "time_in_transit": {
        "percentile_50": 2,
        "percentile_75": 2,
        "percentile_85": 2,
        "percentile_90": 2,
        "percentile_95": 2,
        "percentile_97": 3,
        "percentile_99": 4
      },
      "updated_at": "2023-07-10T17:30:41Z"
    }
  ]
}

GET/shipments/:id/smartrate/delivery_date

Retrieve Estimated Delivery Date and Total Transit Days across all Rates for a Shipment

The Delivery Date endpoint of the SmartRate API will return an EasyPost Estimated Delivery Date as well as a Days in Transit object that contains the expected number of total days the shipment is to be in transit across a variety of percentiles for every Rate for a given Shipment. Transit days are calculated as the number of days (including weekends and holidays) between the first time the carrier acknowledges possession of the Shipment and the first out-for-delivery attempt.

This endpoint requires the parameter planned_ship_date to be provided when called. Planned Ship Date is the date that the user would expect the carrier to take possession of the shipment. Knowing this makes the results of the API extremely accurate.

Example

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Newtonsoft.Json;
using EasyPost;
using EasyPost.Models.API;
using EasyPost.Parameters;

namespace EasyPostExamples
{
    public class Examples
    {
        public static async Task Main()
        {
            string apiKey = Environment.GetEnvironmentVariable("EASYPOST_API_KEY")!;

            var client = new EasyPost.Client(apiKey);

            Shipment shipment = await client.Shipment.Retrieve("shp_...");

            Parameters.Shipment.RetrieveEstimatedDeliveryDate parameters = new()
            {
                PlannedShipDate = "2021-01-01",
            };

            List<RateWithEstimatedDeliveryDate> rates = await client.Shipment.RetrieveEstimatedDeliveryDate(shipment.Id, parameters);

            Console.WriteLine(JsonConvert.SerializeObject(rates, Formatting.Indented));
        }
    }
}

{
  "rates": [
    {
      "easypost_time_in_transit_data": {
        "days_in_transit": {
          "percentile_50": 2,
          "percentile_75": 2,
          "percentile_85": 2,
          "percentile_90": 2,
          "percentile_95": 2,
          "percentile_97": 3,
          "percentile_99": 4
        },
        "easypost_estimated_delivery_date": "2023-04-27",
        "planned_ship_date": "2023-04-25"
      },
      "rate": {
        "carrier": "USPS",
        "carrier_account_id": "ca_4fcd9a658b494a979793bb899a40c5b5",
        "created_at": "2023-04-24T20:17:20Z",
        "currency": "USD",
        "delivery_date": null,
        "delivery_date_guaranteed": false,
        "delivery_days": 2,
        "est_delivery_days": 2,
        "id": "rate_078538dd44654bc79c79163f4a5de5f4",
        "list_currency": "USD",
        "list_rate": 10.27,
        "mode": "test",
        "object": "Rate",
        "rate": 9.15,
        "retail_currency": "USD",
        "retail_rate": 14.05,
        "service": "Priority",
        "shipment_id": "shp_3f16e63fcb614f38b405c417c57203f4",
        "updated_at": "2023-04-24T20:17:20Z"
      }
    }
  ]
}

Shipping Insurance

Insuring your Shipment is as simple as sending us the value of the contents. We charge 0.5% of the value, with a 50 cent minimum, and handle all the claims. All our claims are paid out within 10 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 a Shipment

Request Parameters

param	example
amount	200.00

Example

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Newtonsoft.Json;
using EasyPost;
using EasyPost.Models.API;

namespace EasyPostExamples
{
    public class Examples
    {
        public static async Task Main()
        {
            string apiKey = Environment.GetEnvironmentVariable("EASYPOST_API_KEY")!;

            var client = new EasyPost.Client(apiKey);

            Shipment shipment = await client.Shipment.Retrieve("shp_...");

            shipment = await client.Shipment.Insure(shipment.Id, 200);

            Console.WriteLine(JsonConvert.SerializeObject(shipment, Formatting.Indented));
        }
    }
}

{
  "created_at": "2022-10-17T17:17:51Z",
  "is_return": false,
  "messages": [],
  "mode": "test",
  "options": {
    "currency": "USD",
    "payment": {
      "type": "SENDER"
    },
    "date_advance": 0
  },
  "reference": null,
  "status": "unknown",
  "tracking_code": "9405500106068143633037",
  "updated_at": "2022-10-17T17:17:52Z",
  "batch_id": null,
  "batch_status": null,
  "batch_message": null,
  "customs_info": {
    "id": "cstinfo_0f04d9d807d947469963c7736f83d20c",
    "object": "CustomsInfo",
    "created_at": "2022-10-17T17:17:51Z",
    "updated_at": "2022-10-17T17:17:51Z",
    "contents_explanation": "",
    "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",
    "mode": "test",
    "declaration": null,
    "customs_items": [
      {
        "id": "cstitem_0b24c580be42449eae7d829bc97f1595",
        "object": "CustomsItem",
        "created_at": "2022-10-17T17:17:51Z",
        "updated_at": "2022-10-17T17:17:51Z",
        "description": "T-shirt",
        "hs_tariff_number": "123456",
        "origin_country": "US",
        "quantity": 1,
        "value": "10.0",
        "weight": 5.0,
        "code": "123",
        "mode": "test",
        "manufacturer": null,
        "currency": null,
        "eccn": null,
        "printed_commodity_identifier": null
      }
    ]
  },
  "from_address": {
    "id": "adr_a187bac64e3f11ed878cac1f6b0a0d1e",
    "object": "Address",
    "created_at": "2022-10-17T17:17:51+00:00",
    "updated_at": "2022-10-17T17:17:51+00:00",
    "name": "EasyPost",
    "company": null,
    "street1": "417 Montgomery Street",
    "street2": "5th Floor",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94104",
    "countr

API Documentation

Authenticationlink

EasyPost Objectslink

Errorslink

Error Objectlink

FieldError Objectlink

Common HTTP Status Codeslink

Paginationlink

Request Parameters

ExampleC#/.NETcURLC#/.NETGoJavaNode.jsPHPPythonRuby

Addresseslink

Address Objectlink

Verifications Objectlink

Verification Objectlink

VerificationDetails Objectlink

Address Verification by Countrylink

Create and Verify Addresseslink

Verify an Address

Request Parameters

ExampleC#/.NETcURLC#/.NETGoJavaNode.jsPHPPythonRuby

Retrieve a list of Addresseslink

Request Parameters

ExampleC#/.NETcURLC#/.NETGoJavaNode.jsPHPPythonRuby

Retrieve an Addresslink

ExampleC#/.NETcURLC#/.NETGoJavaNode.jsPHPPythonRuby

Parcelslink

Parcel Objectlink

Predefined Packageslink

Create a Parcellink

Request Parameters

ExampleC#/.NETcURLC#/.NETGoJavaNode.jsPHPPythonRuby

Retrieve a Parcellink

ExampleC#/.NETcURLC#/.NETGoJavaNode.jsPHPPythonRuby

Insuranceslink

Insurance Objectlink

Create an Insurancelink

Request Parameters

ExampleC#/.NETcURLC#/.NETGoJavaNode.jsPHPPythonRuby

Retrieve a list of Insuranceslink

Request Parameters

ExampleC#/.NETcURLC#/.NETGoJavaNode.jsPHPPythonRuby

Retrieve an Insurancelink

Request Parameters

ExampleC#/.NETcURLC#/.NETGoJavaNode.jsPHPPythonRuby

Shipmentslink

Shipment Objectlink

Form Objectlink

PostageLabel Objectlink

Create a Shipmentlink

Request Parameters

ExampleC#/.NETcURLC#/.NETGoJavaNode.jsPHPPythonRuby

Retrieve a list of Shipmentslink

Request Parameters

ExampleC#/.NETcURLC#/.NETGoJavaNode.jsPHPPythonRuby

Retrieve a Shipmentlink

ExampleC#/.NETcURLC#/.NETGoJavaNode.jsPHPPythonRuby

Buy a Shipmentlink

Request Parameters

ExampleC#/.NETcURLC#/.NETGoJavaNode.jsPHPPythonRuby

Buy a Shipment without rating (One-Call Buy)link

Request Parameters

ExampleC#/.NETcURLC#/.NETGoJavaNode.jsPHPPythonRuby

Convert the Label format of a Shipmentlink

ExampleC#/.NETcURLC#/.NETGoJavaNode.jsPHPPythonRuby

Carbon Offsetlink

Carbon Offset Objectlink

Create Shipment with Carbon Offsetlink

Request Parameters

ExampleC#/.NETcURLC#/.NETGoJavaNode.jsPHPPythonRuby

Buy Shipment with Carbon Offsetlink

Request Parameters

ExampleC#/.NETcURLC#/.NETGoJavaNode.jsPHPPythonRuby

One-Call Buy Shipment with Carbon Offsetlink

Request Parameters

ExampleC#/.NETcURLC#/.NETGoJavaNode.jsPHPPythonRuby

Formslink

Forms that may be returned with Shipment objects depending on the carrier and data passed:link

Forms that can be created after a Shipment has been bought:link

Form Objectlink

Create Formlink

Authentication

EasyPost Objects

Errors

Error Object

FieldError Object

Common HTTP Status Codes

Pagination

Example

Addresses

Address Object

Verifications Object

Verification Object

VerificationDetails Object

Address Verification by Country

Create and Verify Addresses

Example

Retrieve a list of Addresses

Example

Retrieve an Address

Example

Parcels

Parcel Object

Predefined Packages

Create a Parcel

Example

Retrieve a Parcel

Example

Insurances

Insurance Object

Create an Insurance

Example

Retrieve a list of Insurances

Example

Retrieve an Insurance

Example

Shipments

Shipment Object

Form Object

PostageLabel Object

Create a Shipment

Example

Retrieve a list of Shipments

Example

Retrieve a Shipment

Example

Buy a Shipment

Example

Buy a Shipment without rating (One-Call Buy)

Example

Convert the Label format of a Shipment

Example

Carbon Offset

Carbon Offset Object

Create Shipment with Carbon Offset

Example

Buy Shipment with Carbon Offset

Example

One-Call Buy Shipment with Carbon Offset

Example

Forms

Forms that may be returned with Shipment objects depending on the carrier and data passed:

Forms that can be created after a Shipment has been bought:

Form Object

Create Form

Example

Options

Options Object

Create a Shipment with Options

Example

Rates

Rates Object

Service Levels

Regenerate Rates for a Shipment

Example

Retrieve Rates for a Shipment

Example

Messages

Message Object

SmartRate

Time in Transit Object