> For the complete documentation index, see [llms.txt](https://help.orderdesk.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.orderdesk.com/integration-setup-guides/shipping-services/easypost-integration.md). # EasyPost Integration EasyPost allows you to create shipping labels for a low cost. Use the EasyPost integration to create and print labels directly from your orders in Order Desk. EasyPost supports a wide variety of carriers. To see their full list [visit their site](https://www.easypost.com/signup?utm_source=orderdesk). This guide will go over how to enable and set up the EasyPost integration within Order Desk. For instructions on how to use EasyPost with Order Desk, see the [Creating Labels with EasyPost](/integration-setup-guides/shipping-services/how-to-create-labels-with-easypost.md) guide. ### Setup If you haven’t already, you will first need to create your own [EasyPost account](https://www.easypost.com/signup?utm_source=orderdesk). #### Add Carriers in EasyPost In your EasyPost account, select all of the carriers that you use. Any carrier you add to your account in EasyPost will be available in Order Desk. To add your carriers in EasyPost, click on your email address in the upper left corner. Select **Carrier Accounts** from the dropdown. ![](https://251457507-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAQOLMUJWMYtrpQ7Oxxca%2Fuploads%2FBBtk07t1t8zumVA2xwCU%2Flegacy-191072de40a704a16797.png?alt=media) #### Get API Keys from EasyPost Get your API Keys from EasyPost. These will need to be added to the integration in Order Desk. To find them, click on your email address in the upper left corner. Select **API Keys** from the dropdown. ![](https://251457507-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAQOLMUJWMYtrpQ7Oxxca%2Fuploads%2F90dRDLFIuHUYqtKNU04r%2Flegacy-356b441ae722d3af7e7a.png?alt=media) #### Connect EasyPost Integration in Order Desk In Order Desk, click on **Manage Integrations** in the left sidebar. Under the **Shipping** tab enable the EasyPost Integration. ![](https://251457507-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAQOLMUJWMYtrpQ7Oxxca%2Fuploads%2FtLUtFmfTQaLGUYqInY3w%2Flegacy-c72910ea929e74cb5eba.png?alt=media) Paste your **Test API Key** and **Production API Key** in the EasyPost integration to enable the connection. ![](https://251457507-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAQOLMUJWMYtrpQ7Oxxca%2Fuploads%2FzrEX5ugexRbTiVWMKBXG%2Flegacy-3f9f488c22174a8f5377.png?alt=media) Please note that Order Desk isn’t able to help find or reset your credentials, as they can only be provided by EasyPost. ### Integration Settings ![](https://251457507-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAQOLMUJWMYtrpQ7Oxxca%2Fuploads%2FzknzfIHWlnWtZi8JPl3L%2Flegacy-fb994b155e5bee7177ac.png?alt=media) #### Mode The integration can be in Test mode or **Live** mode. Test mode allows you to create voided labels and get familiar with the platform. When in Test mode, prices will not reflect EasyPost discounts and EasyPost will not charge for any labels created in Test mode. To see the actual shipping prices, the integration must be set to Live mode and be working with real labels. #### Tracking Webhook URL This custom URL is assigned to your account when the integration is enabled and is used by EasyPost to send tracking status and shipping updates to Order Desk. Enter this URL at EasyPost if you require this functionality. Webhooks can be added from the **Webhooks & Events** page in EasyPost: ![](https://251457507-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAQOLMUJWMYtrpQ7Oxxca%2Fuploads%2F52kmG50C19Jx5YXhbdZj%2Flegacy-05a74b75357cace7ab24.png?alt=media) For more details about how this webhook URL works, scroll down to the [Don’t Send Shipment Notification Until First Carrier Report](#dont-send-shipment-notification-until-first-carrier-report) section. #### Default Signature Choose the default signature type for your packages from the options: * No Signature Required * Adult Signature Required * Signature Required * Default Delivery Confirmation #### Custom Messages Custom Messages are optional messages you can print on the label. The location of the custom message on a label will vary depending on the carrier. Twig is accepted in these fields. UPS labels only support up to two Custom Messages. #### Default Package Size Choose your most common or default package size. These dimensions will be displayed in the EasyPost label creator on each order page. They can be changed from order to order if necessary from within the order page. #### Print Order ID on Label The order number will be added to the label if enabled. #### Domestic and International Label Type Choose the label format for domestic and international labels. Choices are PNG (an image file), PDF (a portable document format) or EPL2 or ZPL (for label printers). Any orders needing customs forms are best printed in PDF format. #### Print Preference Choose whether you want labels to **Print Immediately** or **Not Print Automatically**. This is primarily used if you would like to be able to create labels but not print them right away. #### Incoterm Select DDP for the sender (you) to pay international delivery duties. Select a different incoterm value to pass international delivery duties to the recipient. For more information, please reference [EasyPost’s support article](https://www.easypost.com/what-is-the-difference-between-ddp-and-ddu.html) on the topic or contact EasyPost or your carrier for more details about each incoterm value. Incoterm can also be set on an order-by-order basis using the metadata field **incoterm** with the applicable incoterm value. #### Pre-Fetch Shipping Rates to Speed Up Search Time If selected, prices will be displayed automatically based on default settings. Settings can be adjusted and rates fetched again, if necessary. #### Don’t Send Shipment Notification Until First Carrier Report If this setting is *disabled*, an order will be considered shipped as soon as the label is created by EasyPost. When enabled, this setting waits to mark a package as shipped until the first carrier report “in\_transit” is returned from the [tracking webhook URL](#tracking-webhook-url). This allows for time between when a label is printed and when a package is actually shipped. If enabled, you can also use the **Process Manual Shipments** action in a rule. For this to work, ensure you have *not* set the tracking webhook URL in your EasyPost account, as that will override any rules you set up in Order Desk to process the shipments manually. The tracking will still be added to the order as the label is created, but instead of the shipment added event running immediately, set up a rule using the **Process Manual Shipments** action to have the shipment added event run when your rule runs instead. For example, you can set up a custom button to process the shipments manually when you click the button, rather than when the label is first created or the first carrier report comes back. For more information, read the [How to Use Custom Buttons](/guided-walkthroughs/rules-and-automations/how-to-use-custom-buttons.md) guide. For more information on working with rules, please read the [Order Desk Rule Builder](/start-here/getting-started-series/quick-start-how-customizable-is-order-desk-really.md#the-order-desk-rule-builder) guide. #### Allow USPS Media Mail Rate Request If you ship media mail packages through USPS, select this setting to have media mail rates returned when searching prices from EasyPost. If left unchecked, media mail prices won’t be returned in the search. #### Sender Pays International Delivery Duties If selected, the sender (you) will pay international delivery duties on shipments. #### Use EasyPost Tracking Links If selected, the tracking link added to the shipment information will be the branded EasyPost page rather than the carrier’s tracking page. #### Allow Insurance Purchase After Labels If selected, you can buy insurance separately from the label purchase. ![](https://251457507-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAQOLMUJWMYtrpQ7Oxxca%2Fuploads%2FwRSzXzudKOw0MSChzQJx%2Flegacy-a795ee11c3df5ea3483e.png?alt=media) To purchase insurance after a label has been created, the tracking numbers for an order will appear under the EasyPost label creator. Select the tracking number you want to buy insurance for and follow the prompts. #### Customs Details ![](https://251457507-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAQOLMUJWMYtrpQ7Oxxca%2Fuploads%2FZTNCsKrMcmTICfKe5ECQ%2Flegacy-f4dac58a9097094e0f9b.jpg?alt=media) Fill out the necessary **Customs Details** for international packages. This includes: * The **Customs Signer Name**, which is the name of someone from your store who is responsible for the accuracy of the information on the customs form. Set the name of the person in your organization who is responsible for this. * The **Customs Contents** of the package to declare the type of product(s) being shipped overseas (Merchandise, Documents, Gift, Returned Goods or Sample). * The **Non Delivery Option**, which determines what action is taken if the package is undeliverable (Return or Abandon). * The **Default HS Tariff Number**, a six digit code specifying the type of product being shipped and is required on customs forms when making international shipments. If you aren’t sure what code to use for your store, please see [EasyPost’s guide](https://www.easypost.com/customs-guide.html) or refer directly to the [Harmonized Tariff website](https://hts.usitc.gov/). * The **Importer Tax Number**, which allows setting your Importer Tax Code to be sent to EasyPost in the shipment options to be passed to the carriers that support VAT or IOSS information at EasyPost. This Importer Tax Number will be used if the order doesn’t have the `tax_id` or `IOSS`. If this field is left blank, then the the default IOSS number from the Store Settings will be used instead. Please note that not all carriers currently support IOSS information. Here’s [EasyPost’s IOSS Carrier Update page](https://support.easypost.com/hc/en-us/articles/4403700350989), where you can find a list of all the carriers that are currently supporting IOSS information to be relayed. * The **License Number** is for senders who are registered for EU Economic Operators Registration and Identification number (EORI). If you have an EORI number registered, you must set the EORI number in this field, which will be sent to EasyPost in the shipment options to be relayed to the carriers. See EasyPost’s guide about Customs Information [here](https://www.easypost.com/customs-guide). #### Shipping Class Match ![](https://251457507-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAQOLMUJWMYtrpQ7Oxxca%2Fuploads%2FoBzL78OIsjbY3wC9qeqg%2Flegacy-73c3e66263e58314f712.png?alt=media) Use the Shipping Class Match feature to map the names of any shipping methods you use in your shopping carts to the shipping method names EasyPost uses. When you have a Shipping Class Match set up for EasyPost, you’ll see it available as an option when you’re creating your shipping label. ![](https://251457507-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAQOLMUJWMYtrpQ7Oxxca%2Fuploads%2Fs1JJcWOkdw3QVyHd2frq%2Flegacy-1c8ab735dda1b09a894b.png?alt=media) For more information on how to set up shipping class matches, please read through the [Shipping Class Match guide](/guided-walkthroughs/shipping-fulfillment-and-returns/how-to-set-up-shipping-class-matches.md). #### Default Shipper Information: Setting a Return and From Address ![](https://251457507-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAQOLMUJWMYtrpQ7Oxxca%2Fuploads%2Fo1JqyCvvH8KnoP1TsBl0%2Flegacy-11c84607e814b3e0571b.png?alt=media) #### Default Return Address Set your default return address in the **Default Shipper Information**. This will be used for all orders unless otherwise specified. #### Always Use This Address as Return Address or as From Address Select only one of these options if you need this address to always be used as either the Return Address or the From Address. #### Return Address is different from the Default Return Address To set a return address on an order by order basis, *disable* the **Always Use This Address as Return Address** setting. To set the return address for each order, click on **Set Return Address** in the the order. Choose an available address or add a new one for the order. ![](https://251457507-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAQOLMUJWMYtrpQ7Oxxca%2Fuploads%2FT62txjFSHvBpXClKrz63%2Flegacy-b432096d8556495b98b5.png?alt=media) Available addresses can be stored in your Store Settings. For more information on how to set these up, see the [Store Settings guide](/guided-walkthroughs/using-order-desk/manage-store-settings.md#return-addresses). Use [rules](/start-here/getting-started-series/quick-start-how-customizable-is-order-desk-really.md#the-order-desk-rule-builder) to automatically select available return addresses for specific orders. #### From Address is different from the Default Return Address If the **Always Use This Address as Return Address** setting is *enabled*, the From Address, when different from the default Return Address, can be edited directly from the order page for specific orders. To add the From Address without changing the Return Address, go to the order page and click on **Set Return Address** in the Order Details section. Add the From Address as the Return Address here. The Return address will still be the address set in the EasyPost settings while this new address will act as the From Address. #### Location Type Choose the **Location Type** for the return address, either **Commercial** or **Residential**. #### Custom Return Address Override If you would like to customize one or more fields within a pre-set return address, you can set any of the following field names as order metadata: return\_name return\_company return\_street1 return\_street2 return\_city return\_state return\_zip return\_country return\_phone return\_email Where any of these order metadata fields exist on an order, they will be used to overwrite the same field in the return address for that order. #### Validating Addresses with EasyPost When EasyPost is enabled on a store, the shipping address will have a validation option: ![](https://251457507-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAQOLMUJWMYtrpQ7Oxxca%2Fuploads%2F7xPqGj3aS1yRL8CUZQoq%2Flegacy-4d639e617611afbaa334.png?alt=media) Click the gray **Not Validated by EasyPost** icon and EasyPost will check the address and provide information if it isn’t valid: ![](https://251457507-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAQOLMUJWMYtrpQ7Oxxca%2Fuploads%2FgsGUtYCKA3Kq3LIDNknR%2Flegacy-da64bb8b341711f2baab.png?alt=media) or if it is missing an important detail: ![](https://251457507-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAQOLMUJWMYtrpQ7Oxxca%2Fuploads%2FGQtGJYUwk2hOl6gZixfA%2Flegacy-6b951b3b5f1d52708213.png?alt=media) #### Automating Address Validation You can use rules to automate the address validation step on orders and tell Order Desk what you want to happen to the order depending on the results. In the Rule Builder, set up a rule with the event and filters of your choice, then choose the action **Validate Order Address at EasyPost**: ![](https://251457507-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAQOLMUJWMYtrpQ7Oxxca%2Fuploads%2FgMN3EICb7MMLb8utEOZx%2Flegacy-3a5e40c0321708e356c1.png?alt=media) To take action on orders once the address is checked, set up additional rules using the EasyPost Validation events: * **Address Validated with EasyPost** * **Address Validation Failed with EasyPost** * **Address Validated with Warnings with EasyPost**. Select the actions you want to happen when one of these events happens. If the results of the validation do not appear to be accurate, please contact EasyPost for help. For more information on your options with the Rule Builder, see the [How to Work with Rules](/guided-walkthroughs/rules-and-automations/how-to-work-with-rules.md) guide. #### Working with Taxes, Tariffs, and Customs When your IOSS number is added in your store’s [custom details](#customs-details) or included in the order metadata, we will automatically pass it along in the correct field for your international orders. If you would like to include custom sender tax details, you will need to use them with the following fields: * **SenderTaxId** * **SenderTaxIdType** * **SenderTaxIdIssuingCountry** (Optional) Since **SenderTaxIdIssuingCountry** is optional, if you don’t fill this field out then we will use the information added as the return address country. For custom receiver tax details, use the following fields: * **ReceiverTaxId** * **ReceiverTaxIdType** * **ReceiverTaxIdIssuingCountry** (Optional) If no **ReceiverTaxIdIssuingCountry** field is added, the issue country for the receiver will be used instead. For more information on the different types of taxes and selecting the right one, please refer to the [Tax Identifier](https://support.easypost.com/hc/en-us/articles/4412101923213-Tax-Identifiers) guide from EasyPost. If you would like to include include a customs declaration message you can use the following field as order metadata or checkout data: * **customs\_declaration** Please note that this field only applies to eligible carriers, as specified by EasyPost. #### Item Details The following fields can be set as variations or item metadata for each item in an order. | Field Name | Field Description | | --------------------- | ---------------------------------------------------------------------------------------- | | hs\_tariff | Use to pass tariff data on an item by item basis. The value should be a harmonized code. | | easypost\_description | Use to pass item descriptions. If left blank the item name will be sent. | #### Orders Details The following fields can be set as checkout data or order metadata: | Field Name | Field Description | | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | easypost\_payment\_type | Use to set a payment type. Options are: COLLECT, SENDER, THIRD\_PARTY, and RECEIVER. If no value is set, SENDER will be the default. | | customs\_contents\_type | Use to override the customs settings in your integration settings. Options are: merchandise, returned\_goods, documents, gift, sample, and other. | | freight\_charge | Use to pass additional cost to be added to the invoice of this shipment. Only applies to UPS shipments. | | saturday\_delivery | Use with a value of **1** to request that EasyPost make the order eligible for Saturday delivery. | | invoice\_signature\_required | Use with a value of **1** to require signature image on shipment. If using this field, an image needs to be added to your EasyPost account in advance. | | invoice\_letterhead\_required | Use with a value of **1** to require a letterhead image on shipment. If using this field, an image needs to be added to your EasyPost account in advance. | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://help.orderdesk.com/integration-setup-guides/shipping-services/easypost-integration.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.