About linking API calls across Shipium products

Use partnerReferenceIdentifier to correlate a single order across Shipium's API products: Delivery Promise (Product View and Cart View), Fulfillment Engine, Shipment Planning, and Carrier and Method Selection & Label Generation (Carrier Selection). This field threads your order identifier through the full integration chain for reporting and cross-product correlation.

The standard linking field

partnerReferenceIdentifier is the recommended approach for linking API calls across all Shipium products. Pass the same value in every call to correlate this order across the full API chain.

📘

Not passed to carriers

partnerReferenceIdentifier is stored internally within Shipium and returned in responses for correlation and reporting. It is never transmitted to carriers or printed on labels. To pass references to carriers, use referenceIdentifier through referenceIdentifier5 on the Carrier and Method Selection & Label Generation endpoint — see Carrier reference identifiers below.

Per-product usage

Delivery Promise - Product View

Endpoint: POST /api/v1/deliveryexperience/productview

Pass partnerReferenceIdentifier when retrieving an estimated delivery date at the product page level. This value is stored and returned in the response. Use the same value in all downstream calls to correlate this order across the full chain.

{
  "customerCountryCode": "US",
  "customerPostalCode": "98101",
  "partnerReferenceIdentifier": "ORD-2026-12345"
}

Full details are in the Product View Delivery Promise API documentation.

Delivery Promise - Cart Checkout

Endpoint: POST /api/v1/deliveryexperience/cartDeliveryEstimate

Pass the same partnerReferenceIdentifier value from your Product View call when retrieving delivery estimates at checkout. This links the cart-level estimate back to the product-level browsing session and forward to fulfillment and shipping calls.

{
  "partnerCartId": "74b6e652-8db2-4441-9cf6-85a18a15ca88",
  "customerCountryCode": "US",
  "customerPostalCode": "98101",
  "cartShippingOptions": {
    "shippingLocationOptions": [
      {
        "fromCountryCode": "US",
        "fromPostalCode": "98101"
      }
    ]
  },
  "partnerReferenceIdentifier": "ORD-2026-12345"
}

The Cart Checkout Delivery Promise API documentation includes details.

Fulfillment Engine

Endpoint: POST /api/v1/fe/plans

Pass partnerReferenceIdentifier at the order level within the orders array. Because Fulfillment Engine plans multiple orders in a single call, the field is scoped to each individual order rather than the top-level request. Pass the same value used in your Delivery Promise calls to correlate this order across the full chain.

{
  "orders": [
    {
      "partnerOrderId": "myCustomPartnerOrderId123",
      "orderedDateTime": "2026-03-25T00:00:00Z",
      "destinationAddress": {
        "countryCode": "US",
        "postalCode": "98101",
        "addressType": "residential"
      },
      "orderItemQuantities": [
        {
          "productId": "WIDGET-001",
          "quantity": 1
        }
      ],
      "partnerReferenceIdentifier": "ORD-2026-12345",
      "partnerReferenceIdentifier2": "PLAN:abc-def-ghi"
    }
  ]
}

The Fulfillment Engine API documentation includes details.

Shipment Planning

Endpoint: POST /api/v1/deliveryexperience/shipmentPlanning

Shipment Planning is an optional call used to determine the shipByDate (when the package needs to leave the fulfillment center) and the fcDropByDate (when the order needs to be released to the fulfillment center) for a given desired delivery date. This API is called after Fulfillment Engine and before Carrier Selection and Label Generation when your warehouse operations require advance planning dates.

Pass the same partnerReferenceIdentifier value used in your upstream calls to keep this order correlated across the full chain.

{
  "desiredDeliveryDate": "2026-04-01",
  "shipmentParameters": {
    "destinationAddress": {
      "countryCode": "US",
      "postalCode": "98101"
    },
    "shipFromAddress": {
      "countryCode": "US",
      "postalCode": "90210"
    },
    "shipOption": "Standard"
  },
  "partnerReferenceIdentifier": "ORD-2026-12345"
}

You can find more information in the Shipment Planning API documentation.

Carrier and Method Selection & Label Generation

Endpoint: POST /api/v1/shipment/carrierselection/label

This is where both internal correlation and carrier-facing references come together. Pass partnerReferenceIdentifier for cross-product correlation within Shipium, and use referenceIdentifier through referenceIdentifier5 separately for any references that should reach the carrier and appear on the label.

{
  "currencyCode": "USD",
  "generateLabel": false,
  "shipmentParameters": {
    "partnerShipmentId": "ORD-2026-12345-shipment",
    "orderedDateTime": "2026-03-25T00:00:00Z",
    "partnerReferenceIdentifier": "ORD-2026-12345",
    "partnerReferenceIdentifier2": "PLAN:abc-def-ghi",
    "referenceIdentifier": "ORD-2026-12345",
    "referenceIdentifier2": "PO-98765",
    "shipFromAddress": {
      "countryCode": "US",
      "postalCode": "90210"
    },
    "destinationAddress": {
      "name": "Jane Smith",
      "countryCode": "US",
      "postalCode": "98101"
    },
    "packagingType": {
      "packagingMaterial": "box",
      "linearDimensions": {
        "linearUnit": "in",
        "length": 12,
        "width": 10,
        "height": 8
      }
    },
    "totalWeight": {
      "weightUnit": "lb",
      "weight": 2.5
    }
  }
}

The Carrier and Method Selection & Shipment Label API documentation provides details.

Carrier reference identifiers

referenceIdentifier through referenceIdentifier5 are available on the Carrier and Method Selection & Label Generation endpoint only. These values are transmitted to carriers and may appear on labels, carrier tracking systems, and billing reports.

Additional carrier-facing fields available on this endpoint:

• purchaseOrderIdentifier. Maps to purchase order ID fields on supported carriers
• packageReferenceIdentifier. Correlates parcels to label documents from the carrier; not carrier-facing

🚧

Key distinction

partnerReferenceIdentifier and referenceIdentifier can hold the same value (for example, your order ID), but they serve different purposes. partnerReferenceIdentifier stays within Shipium for cross-product correlation and is never sent to carriers. referenceIdentifier is transmitted to the carrier and may be printed on the label. Always pass both if you need correlation within Shipium and visibility at the carrier level.

Full chain example

The following example shows one order flowing through all five endpoints with the same partnerReferenceIdentifier.