EndShipper Guide

The United States Federal Government and USPS require the legally responsible party to be identified for every item shipped via their services. As many of EasyPost's customers (a.k.a. Platforms) support multiple "EndShippers," it's paramount that EndShippers are registered so that the platform and end shipper stay compliant with the law. You may hear the USPS refer to the EndShipper as the Provider Customer ID (PCID).

The first phase of integration will consist of creating EndShipper objects with our API and storing their references for future use. Creating EndShipper objects, updating them, and retrieving them from our API is straightforward. The real work required during this phase is to determine how you will manage these references within your system and provide them when buying a shipment.

The second phase will consist of including the EndShipper Object reference as a supplemental argument when buying postage for a shipment. The EndShipper Object will be an optional argument, but if it is passed, it will be properly validated as an EndShipper Object created by the user. If an invalid EndShipper Object is passed, an error will be returned. In this way, you can begin incrementally incorporating EndShipper Objects into your Shipment buy flows.

Phase 3 is the transition from the EndShipper Object as an optional argument to a required one. The Federal Government and USPS require every EndShipper to be legally identified, and it is paramount that all Platform customers reach full compliance at here.

Once you have confirmed that all Shipment buy requests are successfully passing an EndShipper Object, please coordinate with your CSM or Support Engineer to schedule the official transition to Phase 3. At this point, an EndShipper Object will become a required argument for any postage purchased using a UspsAccount. If one is not passed, the Shipment Buy request will fail.

Once the Phase 3 transition is complete, you are fully PCID compliant! Please note that it is critical to continue updating existing EndShipper Objects and registering new ones to ensure data quality and EndShipper accuracy.

Shipments created by a Platform on behalf of an EndShipper must assert the EndShipper details when the postage is purchased since the EndShipper is ultimately responsible for the shipment and its contents. Platforms must create EndShipper Objects for each EndShipper they are purchasing USPS postage on behalf of.

The EndShipper Object address and contact details are of the person or business entity responsible for the shipment and not necessarily the shipping location. For example, the business headquarters may have a different address and contact info than the actual warehouse the shipment is being shipped from.

EndShipper Objects must be created prior to the first postage purchase for that EndShipper. The public_id associated with each EndShipper Object must then be stored in the Platform's system for use later.

A typical workflow for a Platform may look like the following:

1. EndShipper (the Platform's user) requests to purchase postage within the Platform's software suite.

2. Platform retrieves the public_id of that user's EndShipper Object stored on the platform's system.

   1. If no EndShipper Object exists for this EndShipper, the Platform creates an EndShipper Object prior to sending through the request to purchase postage.

3. For Platforms utilizing Shipment Objects to buy postage:

   1. Platform creates a shipment on the EndShipper's behalf.
   2. Platform buys the shipment and specifies the EndShipper Object public_id via the top-level end_shipper_id key.

4. For Platforms utilizing Batches or Orders to buy postage:

   1. A Shipment Option parameter has been added named end_shipper_id. This option must be specified at the time of creating the Shipment object.
   2. Platform creates a shipment on the EndShipper's behalf.
   3. NOTE: Shipment Buy calls with EndShipper information passed as a top-level parameter (step 3) supersede the Shipment Option.

EndShipper Objects are fully-qualified Address objects and require every field to be filled with two exceptions:

1. name and company fields. At least one of these fields must be filled (when both are present, name will take precedence).
2. street2 field. This field can be empty if the address does not include multiple lines.

The values for name and company must be an actual person's name or company's name respectively. Per USPS regulations, it cannot be a vague value such as 'Shipping Manager' or 'Mail Room' for legal identification purposes.

Once EndShipper Objects have been created, you must keep track of their public id in order to use them when purchasing postage. This could be in a local database table (recommended) that associates each EndShipper with one of your customers, or pulling down your EndShippers via the 'Retrieve all EndShipper' function.

The same EndShipper should not have multiple instances created. Instead, the EndShipper object id should be cached within the Platform's system, and retrieved each time postage is being purchased for that specific EndShipper.