Understanding Shipment & Shipping Fields

The Shipment object in a Purchase Order controls where and how goods are shipped. This guide explains each shipping-related field and how they work together.

For the full schema reference, see the official PromoStandards Purchase Order spec.

Who Handles Shipping?

There are three main scenarios for who handles shipping:

customerPickup

When true, the distributor arranges their own pickup from the supplier’s warehouse. No carrier or freight information is needed in this case.

FreightDetails

Specifies how the shipment should be sent:

• carrier — The shipping vendor name (e.g. "UPS", "FEDEX"). Optional.
• service — The service level code (e.g. "GROUND", "2DAY", "NEXTDAY"). Optional.

Both fields are optional per the SOAP spec (minOccurs="0"); some suppliers may only need the carrier.

ThirdPartyAccount

When provided, the supplier bills shipping to the distributor’s own carrier account. It contains:

• accountName — Name on the carrier account
• accountNumber — The carrier account number
• ContactDetails — Contact information for the paying entity

When null, the supplier uses their own shipping account.

Shipment Behavior Fields

blindShip

When true, the supplier ships without revealing their identity to the end customer. The packing slip and label show the distributor’s info (or no supplier branding). This is standard practice for most distributors to protect their supplier relationships.

packingListRequired

When true, the supplier must include a packing list with the shipment. The packing list typically itemizes the contents of the package.

allowConsolidation

When true, the supplier may combine this shipment with other shipments heading to the same destination. This can reduce shipping costs but may delay delivery if the supplier waits to consolidate. When false, this shipment must be sent independently.

JSON Examples

Supplier ships with their account (most common)

{
  "Shipment": {
    "customerPickup": false,
    "ShipTo": {
      "customerName": "Acme Corp",
      "address1": "123 Main St",
      "city": "Anytown",
      "state": "CA",
      "postalCode": "90210",
      "country": "US"
    },
    "FreightDetails": {
      "carrier": "UPS",
      "service": "GROUND"
    },
    "ThirdPartyAccount": null,
    "blindShip": true,
    "packingListRequired": true,
    "allowConsolidation": false
  }
}

Distributor’s own carrier account

{
  "Shipment": {
    "customerPickup": false,
    "ShipTo": {
      "customerName": "Acme Corp",
      "address1": "123 Main St",
      "city": "Anytown",
      "state": "CA",
      "postalCode": "90210",
      "country": "US"
    },
    "FreightDetails": {
      "carrier": "FEDEX",
      "service": "2DAY"
    },
    "ThirdPartyAccount": {
      "accountName": "Acme Distribution",
      "accountNumber": "123456789",
      "ContactDetails": {
        "attentionTo": "Shipping Dept",
        "address1": "456 Warehouse Blvd",
        "city": "Commerce",
        "state": "CA",
        "postalCode": "90040",
        "country": "US"
      }
    },
    "blindShip": true,
    "packingListRequired": true,
    "allowConsolidation": false
  }
}

Customer pickup

{
  "Shipment": {
    "customerPickup": true,
    "ShipTo": {
      "customerName": "Acme Corp",
      "address1": "123 Main St",
      "city": "Anytown",
      "state": "CA",
      "postalCode": "90210",
      "country": "US"
    },
    "blindShip": false,
    "packingListRequired": false,
    "allowConsolidation": false
  }
}