# 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.

| Field | Type | Carrier-facing? | Available on |
| --- | --- | --- | --- |
| `partnerReferenceIdentifier` | String | No | Product View, Cart View, Fulfillment Engine, Shipment Planning, Carrier and Method Selection & Label Generation |
| `partnerReferenceIdentifier2` | String | No | Fulfillment Engine, Shipment Planning, Carrier and Method Selection & Label Generation |

> 📘
>
> ### 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.

JSON

```json
{
  "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.

JSON

```json
{
  "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.

JSON

```json
{
  "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.

JSON

```json
{
  "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.

JSON

```json
{
  "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.

| Shipium field | FedEx | UPS | USPS | DHL | UPS MI |
| --- | --- | --- | --- | --- | --- |
| `referenceIdentifier` | CUSTOMER_REFERENCE | Reference 1 | ReferenceID | packageDescription | PackageID |
| `referenceIdentifier2` | P_O_NUMBER | Reference 2 | ReferenceID2 | billingReference1 | CostCenter |
| `referenceIdentifier3` | INVOICE_NUMBER | Reference 3 | ReferenceID3 | billingReference2 | — |
| `referenceIdentifier4` | DEPARTMENT_NUMBER | Reference 4 | ReferenceID4 | — | — |
| `referenceIdentifier5` | SHIPMENT_INTEGRITY | Reference 5 | — | — | — |

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`.

| Step | API | Field | Value | Notes |
| --- | --- | --- | --- | --- |
| 1 | Product View | `partnerReferenceIdentifier` | `"ORD-2026-12345"` | Customer sees estimated delivery date |
| 2 | Cart View | `partnerReferenceIdentifier` | `"ORD-2026-12345"` | Customer selects shipping at checkout |
| 3 | Fulfillment Engine | `orders[].partnerReferenceIdentifier` | `"ORD-2026-12345"` | System determines fulfillment origin |
| 4 | Shipment Planning | `partnerReferenceIdentifier` | `"ORD-2026-12345"` | Determines ship-by and fulfillment center drop-by dates |
| 5 | Carrier and Method Selection & Label Generation | `partnerReferenceIdentifier` | `"ORD-2026-12345"` | Internal — Shipium only, not sent to carrier |
| 5 | Carrier and Method Selection & Label Generation | `referenceIdentifier` | `"ORD-2026-12345"` | Transmitted to FedEx, printed on label |
| 5 | Carrier and Method Selection & Label Generation | `referenceIdentifier2` | `"PO-98765"` | Transmitted to FedEx |