# Get started

To use the Product View Delivery Promise API, you must first configure your account. Guidance can be found in the [Delivery Promise](https://docs.shipium.com/docs/delivery-promise) documentation. This document provides instructions for using the API.

# Retrieve an estimated delivery date (EDD) for your product detail pages with the Product View Delivery Promise API

The Shipium Product View Delivery Promise API is designed to be flexible to fit your organization’s business strategy and technical capabilities. All API calls assume you're using one of the authentication mechanisms detailed in our [authentication documentation](https://docs.shipium.com/docs/authentication). The endpoint for all Product View Delivery Promise API calls is included in the table below.

| API type | API endpoint |
| --- | --- |
| POST | `https://api.shipium.com/api/v1/deliveryexperience/productview` |

## Request and response fields for API calls

The following tables provide required, conditional, and optional fields for calling the Product View Delivery Promise API. You can find additional support in the [Product View Delivery Estimate API Reference](https://docs.shipium.com/reference/createdeliveryestimate).

### Required request fields

| Request field | Details |
| --- | --- |
| `customerCountryCode` | **Type:** String (enumeration)\n**Format:** Limited to 2 characters and [ISO 3166](https://docs.shipium.com/docs/non-us-address-formats) standards\n**Description:** Shipment's destination country |
| `customerPostalCode` | **Type:** String\n**Format:** Limited to valid [USPS postal ZIP codes](https://faq.usps.com/s/article/ZIP-Code-The-Basics)\n**Description:** Shipment's destination postal code |

### Conditional request fields

| Request field | Details |
| --- | --- |
| `options.shippingOptions.fromCountryCode` | **Type:** String\n**Format:** Limited to 2 characters and [ISO 3166](https://docs.shipium.com/docs/non-us-address-formats) standards\n**Condition:** Either the `fromCountryCode` and `fromPostalCode` or the `originId` must be provided.\n**Description:** Shipment's origin country |
| `options.shippingOptions.fromPostalCode` | **Type:** String\n**Condition:** Either the `fromCountryCode` and `fromPostalCode` or the `originId` must be provided.\n**Description:** Shipment's origin country appropriate postal code |
| `options.shippingOptions.originId` | **Type:** String\n**Example:**`origin-id-123`\n**Condition:** Either the `fromCountryCode` and `fromPostalCode` or the `originId` must be provided.\n**Description:** A unique identifier for the origin, whether one your organization assigned (`partnerProvided`) or a Shipium ID |

### Optional request fields

| Request field | Details |
| --- | --- |
| `requestDateOverride` | **Type:** String (date-time)\n**Format:** Limited to the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) standard\n**Example:**`2019-10-31T00:00:00Z`\n**Description:** Dictate the base calculation of when the request happened. This field allows you to specify the request as though it had happened on a different date and/or time. |
| `shipDateOverride` | **Type:** String\n**Format:** Either the [ISO 8601 standard](https://www.iso.org/iso-8601-date-and-time-format.html) date or a local date (`yyyy-mm-dd`)\n**Description:** Dictate the date that the origin will ship the item. |
| `options.shippingOptions.shipOption` | **Type:** String (enumeration)\n**Values:**`standard`, `same_day`, `next_day`, `two_day`, `three_day`\n**Description:** Retrieve the estimate for a different [ship option](https://docs.shipium.com/docs/shipment-ship-option-overview); the default value is `standard`. |
| `options.shippingOptions.estimateSource` | **Type:** String (enumeration)\n**Values:**`ShipiumCalculated`, `PartnerProvided`, `CarrierProvided`, `Unknown`\n**Description:** The source used to generate the estimate |
| `options.shippingOptions.deliveryBehaviorOverrides` | **Type:** Object\n**Description:** Override your organization's account-level [weekend and holiday delivery](https://docs.shipium.com/docs/weekend-and-holiday-delivery) behavior for this request. These overrides apply to the `shipOption` specified in the same `shippingOptions` object. When provided, these settings take precedence over your default configuration. Each field within the object is optional and can be set independently. If omitted, your account-level settings apply. |
| `options.shippingOptions.deliveryBehaviorOverrides.saturdayDeliveryBehavior` | **Type:** String (enumeration)\n**Values:**`ALLOW`, `NON_DELIVERY_DAY`, `NON_TRANSIT_NON_DELIVERY_DAY`\n**Description:** Controls how Saturdays affect delivery estimates. `ALLOW` treats Saturday as a regular transit and delivery day. `NON_DELIVERY_DAY` allows transit but no final delivery; if the calculated delivery date falls on Saturday, it shifts to the next available delivery day. `NON_TRANSIT_NON_DELIVERY_DAY` excludes Saturday from transit calculations entirely — no transit movement or delivery occurs. When provided, this overrides your organization's configuration in the Shipium platform for [Saturday deliveries](https://docs.shipium.com/docs/weekend-and-holiday-delivery). |
| `options.shippingOptions.deliveryBehaviorOverrides.sundayDeliveryBehavior` | **Type:** String (enumeration)\n**Values:**`ALLOW`, `NON_DELIVERY_DAY`, `NON_TRANSIT_NON_DELIVERY_DAY`\n**Description:** Controls how Sundays affect delivery estimates. `ALLOW` treats Sunday as a regular transit and delivery day. `NON_DELIVERY_DAY` allows transit but no final delivery; if the calculated delivery date falls on Sunday, it shifts to the next available delivery day. `NON_TRANSIT_NON_DELIVERY_DAY` excludes Sunday from transit calculations entirely — no transit movement or delivery occurs. When provided, this overrides your organization's configuration in the Shipium platform for [Sunday deliveries](https://docs.shipium.com/docs/weekend-and-holiday-delivery). |
| `options.shippingOptions.deliveryBehaviorOverrides.holidayDeliveryBehavior` | **Type:** String (enumeration)\n**Values:**`ALLOW`, `NON_DELIVERY_DAY`, `NON_TRANSIT_NON_DELIVERY_DAY`\n**Description:** Controls how holidays affect delivery estimates. `ALLOW` treats the holiday as a regular transit and delivery day. `NON_DELIVERY_DAY` allows transit but no final delivery; if the calculated delivery date falls on the holiday, it shifts to the next available delivery day. `NON_TRANSIT_NON_DELIVERY_DAY` excludes the holiday from transit calculations entirely — no transit movement or delivery occurs. When provided, this overrides your organization's configuration in the Shipium platform for [holiday deliveries](https://docs.shipium.com/docs/weekend-and-holiday-delivery). |
| `partnerReferenceIdentifier` | **Type:** String\n**Description:** An optional identifier your organization provides, used for reporting and cross-product correlation across Shipium APIs. This value is stored and returned in the response. Pass the same value in your Cart Checkout and downstream Carrier Selection calls to correlate this order across the full API chain. This value is not passed to carriers. See [Link API Calls Across Shipium Products](https://docs.shipium.com/docs/link-api-calls-across-shipium-products) for the full cross-product linking guide. |

### Response attributes

The Product View Delivery Promise response attributes are defined in the following table.

| Response attribute | Description |
| --- | --- |
| `deliveryEstimateId` | Unique Shipium-generated ID related to the response |
| `shipEstimateDate` | A valid date in ISO 8601 format representing the estimated ship date to a customer configured in the call parameters (e.g., 2023-10-31T00:00:00Z) |
| `shipEstimateDateUTC` | A valid date in ISO 8601 format with UTC timezone representing the estimated ship date to a customer configured in the call parameters (e.g., 2023-10-31T00:00:00Z) |
| `deliveryEstimateDate` | Shipium's estimated delivery date (EDD) in the local timezone of the delivery postal code (`customerPostalCode`) |
| `deliveryEstimateDateUTC` | A valid date in ISO 8601 format with UTC timezone representing the estimated delivery date to a customer configured in the call parameters (e.g., 2023-10-31T00:00:00Z) |
| `estimateSource` | The time in transit (TNT) calculation method that was used when calculating this EDD |
| `estimatedTimeInTransitDays` | An integer value of the time in transit (TNT) in days |

## Shipium assumptions for the Product View Delivery Promise API

- **Origin**  
The shipment will ship from the closest origin to the customer based on distance.  
- **Shipment date**  
The shipment will ship based on the timestamp of the request plus the configured click-to-ship time and the configured schedule at the origin.  
- **Ship method**  
Standard Ground

## Retrieve an EDD for a shipment at product view (primary use case)

### Example cURL call

```curl
curl --request POST
  --url https://api.shipium.com/api/v1/deliveryexperience/productview
  --header 'accept: application/json'
  --header $AUTHSTRING
  --header 'content-type: application/json'
  --data 'INSERT REQUEST BODY FROM BELOW'
```

### Example request body

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

### Example response

```json
{
    "deliveryEstimateId": "da2959d6-248f-4dac-a557-c6b06a3f826f",
    "requestDate": "2024-08-20T18:52:06.357Z",
    "shipEstimateDate": "2024-08-22T17:00:00-04:00",
    "shipEstimateDateUTC": "2024-08-22T21:00:00Z",
    "deliveryEstimateDate": "2024-08-30T20:00:00-07:00",
    "deliveryEstimateDateUTC": "2024-08-31T03:00:00Z",
    "estimateSource": "ShipiumCalculated",
    "estimatedTimeInTransitDays": 8,
    "customerCountryCode": "US",
    "customerPostalCode": "98101",
    "shippingOrigin": {
        "countryCode": "US",
        "postalCode": "43068",
        "shipiumOriginId": "b1c9d24e-86f1-4bd6-b6dc-661a6f16e824"
  },
    "partnerReferenceIdentifier": "ORD-2026-12345"
}
```

## Augmentations to the EDD request (additional use cases)

Your organization may choose to augment your EDD request by including any of the following optional fields, which will generally enhance the accuracy of our EDD calculation.

### Request date override

`requestDateOverride`  
Dictate the base calculation of when the request happened. This field allows you to specify the request as though it had happened on a different date and/or time.

#### Example request body

```json
{
  "customerCountryCode": "US",
  "customerPostalCode": "98101",
  "requestDateOverride": "2024-08-19T18:52:06.357Z",
  "partnerReferenceIdentifier": "ORD-2026-12345"
}
```

#### Example response

### Shipping origin override

`shippingOrigin`  
Dictate the origin that will fulfill the shipment by using the `originID`.

#### Example request body by origin ID

```json
{
  "customerCountryCode": "US",
  "customerPostalCode": "98101",
  "options": {
        "shippingOptions": {
            "originId": "194d28d5-53b3-4c80-badc-0793ba220932"
        }
  },
  "partnerReferenceIdentifier": "ORD-2026-12345"
}
```

#### Example response by origin ID

### Ship date override

`shipDateOverride`  
Dictate the date that the origin will ship the item.

#### Example request body

```json
{
  "customerCountryCode": "US",
  "customerPostalCode": "98101",
  "shipDateOverride": "2024-08-19T18:52:06.357Z",
  "partnerReferenceIdentifier": "ORD-2026-12345"
}
```

#### Example response

### Ship option override

`shipOption`  
Retrieve the estimate for a different ship option.

#### Example request body

```json
{
  "customerCountryCode": "US",
  "customerPostalCode": "98101",
  "options": {
        "shippingOptions": {
            "shipOption": "TwoDay"
        }
  },
  "partnerReferenceIdentifier": "ORD-2026-12345"
}
```

#### Example response

### Weekend and holiday delivery overrides

Use the `deliveryBehaviorOverrides` object to override your account-level weekend and holiday settings on a per-request basis. Overrides apply to the specific `shipOption` in the same request, allowing granular control.

#### Example request body

```json
{
  "customerCountryCode": "US",
  "customerPostalCode": "98101",
  "options": {
    "shippingOptions": {
      "shipOption": "NextDay",
      "deliveryBehaviorOverrides": {
        "saturdayDeliveryBehavior": "ALLOW",
        "sundayDeliveryBehavior": "NON_TRANSIT_NON_DELIVERY_DAY"
      }
    }
  },
  "partnerReferenceIdentifier": "ORD-2026-12345"
}
```

#### Example response

```json
{
  "deliveryEstimateId": "da2959d6-248f-4dac-a557-c6b06a3f826f",
  "requestDate": "2024-08-20T18:52:06.357Z",
  "shipEstimateDate": "2024-08-22T17:00:00-04:00",
  "shipEstimateDateUTC": "2024-08-22T21:00:00Z",
  "deliveryEstimateDate": "2024-08-24T20:00:00-07:00",
  "deliveryEstimateDateUTC": "2024-08-25T03:00:00Z",
  "estimateSource": "ShipiumCalculated",
  "estimatedTimeInTransitDays": 2,
  "customerCountryCode": "US",
  "customerPostalCode": "98101",
  "shippingOrigin": {
    "countryCode": "US",
    "postalCode": "43068",
    "shipiumOriginId": "b1c9d24e-86f1-4bd6-b6dc-661a6f16e824"
  },
  "options": {
    "shippingOptions": {
      "shipOption": "NextDay",
      "deliveryBehaviorOverrides": {
        "saturdayDeliveryBehavior": "ALLOW",
        "sundayDeliveryBehavior": "NON_TRANSIT_NON_DELIVERY_DAY"
      }
    }
  },
  "partnerReferenceIdentifier": "ORD-2026-12345"
}
```