Predefined PUDO shipments

What is predefined PUDO? link

Predefined PUDO (Pick-Up Drop-Off) is a package delivery model where the retailer manages the pickup-point selection in their own checkout process.

This means the retailer provides the options for a customer to choose the pickup location of their order. The retailer provides this information to Sorted when the shipment is created.

How predefined PUDO works in Shipments API link

Any shipments requiring predefined PUDO still requires the same data structure that’s provided when creating a shipment. However, certain fields are required so that the pickup location, sender, and recipient can be correctly identified.

Mandatory fields for a predefined PUDO shipment link

Predefined PUDO shipments require these mandatory details:

1. Three address objects (origin, destination, and recipient); and
2. The carrier service details (selected_carrier_details)

To view a complete example of what the create shipment body should contain, please scroll down to the json example.

Following a successful create shipment request you can:

• Optionally create a quote; and/or
• Allocate the shipment

Address objects link

The addresses object must contain three address entries, each representing a different entity involved in the shipment lifecycle.

1. origin address
2. destination address (with mandatory fields)
3. recipient address (with mandatory fields)

1. Origin address link

The origin address represents the sender location dispatching the package. This is typically a warehouse, fulfilment centre, or retail store.

The origin address must contain:

• address_type: "origin"
• shipping_location_reference

Origin address example link

Using shipping_location_reference to provide the address information of the origin.

  {
  "address_type": "origin",
  "shipping_location_reference": "sl_12345"
}
  

2. Destination address (the pickup location) link

The destination address represents the pickup location selected by the customer during checkout. This must be the physical address of the PUDO location.

The destination address must contain:

• address_type: "destination"
• The destination (pickup) location address details
• pudo_location_reference
• A contact object containing the recipient’s contact details

Destination address example with contact object link

  {
  "address_type": "destination",
  "pudo_location_reference": "LOCATION123",
  "contact": {
    "first_name": "Jane",
    "last_name": "Doe",
    "contact_details": {
      "email": "jane.doe@email.com"
    }
  },
  "address_line1": "Pickup Store",
  "locality": "Manchester",
  "postal_code": "M2 2BB",
  "country_iso_code": "GB"
}
  

3. Recipient address link

The recipient address represents the person collecting the package.

This must include:

• address_type: "recipient"
• A contact object containing the recipient’s contact details
• The recipient address details

Recipient address example with contact object link

  {
  "address_type": "recipient",
  "contact": {
    "first_name": "Jane",
    "last_name": "Doe",
    "contact_details": {
      "email": "jane.doe@email.com"
    }
  },
  "address_line1": "10 Example Street",
  "locality": "Manchester",
  "postal_code": "M3 3CC",
  "country_iso_code": "GB"
}
  

Carrier service reference link

For predefined PUDO shipments, the create shipment request must also include a selected_carrier_details object which defines the carrier service the retailer intends to allocate with.

This object contains:

• service_reference — the carrier service reference
• type — must be set to "pick_up"

Selected carrier service example link

  {
  "selected_carrier_details": {
    "service_reference": "carrier_service_reference",
    "type": "pick_up"
  }
}
  

With the appropriate address and carrier service properties provided, the shipment can then be sent for allocation. For more information, see the section below..

Example create shipment request link

Below is a simplified example of a Create Shipment request containing the required fields for a predefined PUDO shipment.

  POST /pro/shipments
  

JSON sample - inc. addresses & service_carrier_details link

  {
  "addresses": [
    {
      "address_type": "origin",
      "shipping_location_reference": "sl_12345"
    },
    {
      "address_type": "destination",
      "pudo_location_reference": "LOCATION123",
      "contact": {
        "first_name": "Jane",
        "last_name": "Doe",
        "contact_details": {
          "email": "jane.doe@email.com"
        }
      },
      "address_line1": "Pickup Store",
      "locality": "Manchester",
      "postal_code": "M2 2BB",
      "country_iso_code": "GB"
    },
    {
      "address_type": "recipient",
      "contact": {
        "first_name": "Jane",
        "last_name": "Doe",
        "contact_details": {
          "email": "jane.doe@email.com"
        }
      },
      "address_line1": "10 Example Street",
      "locality": "Manchester",
      "postal_code": "M3 3CC",
      "country_iso_code": "GB"
    }
  ],
  "selected_carrier_details": {
    "service_reference": "carrier_service_reference",
    "type": "pick_up"
  }
}
  

Carrier-specific fields link

While the create shipment request structure is largely consistent across carriers, some carriers may require additional or carrier-specific fields to successfully create a shipment.

These fields may include:

• Additional address attributes
• Carrier-specific service references
• PUDO (Pick Up / Drop Off) location identifiers
• Additional customs or label properties
• Carrier-specific metadata

The exact requirements can vary depending on the carrier and service being used. For example, some carriers may require specific identifiers for pickup locations, while others may require additional customs information for international shipments.

When onboarding a new carrier, it may therefore be necessary to include additional fields beyond the standard shipment schema to meet the carrier’s API requirements. These requirements will be documented once confirmed.

Optional: Create quotes link

After creating a shipment, you can optionally request delivery quotes using the create quote endpoint.

This endpoint generates quotes based on the shipment details and returns available carrier services, delivery dates, and pricing.

  POST /pro/shipments/quote
  

Quotes can be used to review available delivery options before allocating the shipment.

Allocate the shipment link

After the shipment has been created, allocate it using the same service_reference supplied in the shipment creation request and pass as carrier_service_reference when allocating.

The following allocation endpoint can be used - Allocate Shipment with Carrier Service

Validation behaviour link

Allocation fails if any required information is missing or invalid.

Common validation failures link