# Get package shipping details

This operation provides package information in batches once warehouse
activity started in order fulfillment. Provides filters options to search
for packages by ship date range, last activity date range, shipping carrier,
order numbers and options to paginate through the result set.
**Choosing a date filter**
- `ShipDateRange`
 filters on the date a package shipped, which is set once

and does not change. Use it for reporting on outbound volume, billing, and

reconciliation. Packages that have not shipped yet are not returned.
- `LastActivityDateRange`
 filters on the most recent activity on a package,

such as a status change, tracking scan, delivery, return, or address change.

Use it for incremental syncs: store the time of your last pull and request

activity since then.

For example, a package shipped on Oct 1 and delivered on Oct 5 is not returned
by a ship date range of Oct 4–6, but is returned by a last activity range of
Oct 4–6.
**Example: get all packages for a year (JavaScript)**
The date range is limited to 31 days, so the script requests one month at a
time and pages through each month with `Skip` and `Top`. It also retries when
the API returns `429 Too Many Requests`.

```javascript
// Retrieve all packages with activity during a calendar year.
// LastActivityDateRange is limited to 31 days, so the year is requested
// one month at a time, and each month is paged through with Skip/Top.

const BASE_URL = 'https://api.wineshipping.com/v3';
const AUTH = {
  UserKey: 'YOUR_USER_KEY',
  Password: 'YOUR_PASSWORD',
  CustomerNo: 'YOUR_CUSTOMER_NO',
};
const PAGE_SIZE = 500;

const pad = (n) => String(n).padStart(2, '0');

// Formats a Date as 'mm/dd/yyyy hh:mm:ssZ' (UTC).
function formatUtc(date) {
  return `${pad(date.getUTCMonth() + 1)}/${pad(date.getUTCDate())}/${date.getUTCFullYear()} `
    + `${pad(date.getUTCHours())}:${pad(date.getUTCMinutes())}:${pad(date.getUTCSeconds())}Z`;
}

async function getPackagesPage(lastActivityDateRange, skip) {
  for (let attempt = 1; ; attempt++) {
    const response = await fetch(`${BASE_URL}/api/Tracking/GetPackages`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        Authentication: AUTH,
        LastActivityDateRange: lastActivityDateRange,
        Skip: skip,
        Top: PAGE_SIZE,
      }),
    });

    // Back off and retry when rate limited.
    if (response.status === 429 && attempt < 5) {
      await new Promise((resolve) => setTimeout(resolve, 1000 * 2 ** attempt));
      continue;
    }
    if (!response.ok) {
      throw new Error(`GetPackages failed (${response.status}): ${await response.text()}`);
    }
    return response.json();
  }
}

async function getPackagesForYear(year) {
  const packages = [];

  for (let month = 0; month < 12; month++) {
    const start = new Date(Date.UTC(year, month, 1, 0, 0, 0));
    const end = new Date(Date.UTC(year, month + 1, 0, 23, 59, 59)); // last day of month
    const range = `${formatUtc(start)} - ${formatUtc(end)}`;

    let skip = 0;
    let result;
    do {
      result = await getPackagesPage(range, skip);
      packages.push(...(result.Packages ?? []));
      skip += PAGE_SIZE;
    } while (result.MoreRecords);

    console.log(`${range}: ${result.TotalRecordCount} packages`);
  }

  return packages;
}

getPackagesForYear(2025)
  .then((packages) => console.log(`Total packages for the year: ${packages.length}`))
  .catch((error) => console.error(error));
```
Please also see our event-based API:
[event driven tracking](../../../../docs/EventDrivenTracking) `webhook`

Endpoint: POST /api/Tracking/GetPackages
Version: 3.1.4

## Request fields (application/json):

  - `Authentication` (object, required)
    Credentials are required for all API operations.

  - `Authentication.UserKey` (string, required)
    Example: C445598CB576468EA35FBB22C55584EF

  - `Authentication.Password` (string, required)
    Example: AF63FDAC1E704DC1AC9460F669ABF107

  - `Authentication.CustomerNo` (string, required)
    Example: 10703

  - `ShipDateRange` (string)
    Date range to filter packages by their ship date. The range must be no longer than 31 days.
Use the format `[datetime]-[datetime]`, where each `[datetime]` is one of:
- `mm/dd/yyyy`
 (date only)
- `mm/dd/yyyy hh:mm:ssZ`
 (UTC time)
- `mm/dd/yyyy hh:mm:ss+00:00`
 (time in a specific time zone; replace
`+00:00`
 with the desired offset from UTC)

To capture all packages shipped on a single day, provide a full-day range, for example `12/19/2025 00:00:00Z - 12/19/2025 23:59:59Z`.
    Example: 12/01/2026 00:00:00Z - 12/31/2026 23:59:59Z

  - `LastActivityDateRange` (string)
    Date range to filter packages by their most recent activity. The range must be no longer than 31 days.
Use the format `[datetime]-[datetime]`, where each `[datetime]` is one of:
- `mm/dd/yyyy`
 (date only)
- `mm/dd/yyyy hh:mm:ssZ`
 (UTC time)
- `mm/dd/yyyy hh:mm:ss+00:00`
 (time in a specific time zone; replace
`+00:00`
 with the desired offset from UTC)

To capture all activity on a single day, provide a full-day range, for example `12/19/2025 00:00:00Z - 12/19/2025 23:59:59Z`.
    Example: 12/01/2026 00:00:00Z - 12/31/2026 23:59:59Z

  - `ShippingCarrier` (string)

  - `OrderNumbers` (array)
    Array of up to 100 order numbers is allowed

  - `Skip` (number)

  - `Top` (number)

## Request examples:

  - `Search By Last Activity Date Range` (unknown)

  - `Search By Ship Date Range` (unknown)

  - `Search By Shipping Carrier` (unknown)

  - `Search By Order Numbers` (unknown)

## Response 200:

  - `200` (unknown)
    OK

## Response 200 fields (application/json):

  - `TransactionReferenceNumber` (string)
    Example: 8a806bdb-49ee-4465-86a1-fa10e47d22a1

  - ` LatestActivityTimestamp` (string)
    LastActivityTimestamp field represents the latest timestamp from the filtered timeframe. If no data is returned, it returns the latest timestamp in our dataset preceding the timeframe.
    Example: 01/01/2025 21:09:53

  - `TotalRecordCount` (integer)
    Example: 1

  - `Skip` (integer)
    Example: 0

  - `Top` (integer)
    Example: 500

  - `MoreRecords` (boolean)

  - `Packages` (array)

  - `Packages.OrderNumber` (string)
    Example: 08312021-FO-9808

  - `Packages.Carrier` (string)
    Carrier Code used to ship the order
    Example: FEX

  - `Packages.Service` (string)
    Code of the carrier service level used to ship the order
    Example: GRND

  - `Packages.TrackingNo` (string)
    Tracking number for the package
    Example: 934076697393

  - `Packages.TrackingURL` (string)
    hyperlink for carrier package tracking (when available from the carrier)
    Example: https://www.fedex.com/apps/fedextrack/?tracknumbers=934076697393

  - `Packages.RequestedShipDate` (string)
    The requested shipping date specified upon order creation in the Wineshipping system and updated dynamically based on the order processing status.

  - `Packages.ShipDate` (string)
    Requested ship date submitted with the sales order until the package is processed for shipment and receives a shipment confirmation date (actual ship date)

  - `Packages.EstimatedDeliveryDate` (string)
    Upon Sales Order processing, this is the Estimated Delivery Date for the Sales Order based on the Requested Shipping Date submitted, and it will update within 4 hours of any changes made to the Sales Order’s Requested Shipping date. Upon origin scan for each package, this date will be representative of the carrier’s published estimate. Support is presently for FEX and UPS carriers.

  - `Packages.Status` (string)
    See package [fulfillment status codes](../../../../docs/codes/fulfillmentstatuscodes) for possible values.

  - `Packages.StatusDescription` (string)
    See package [fulfillment status descriptions](../../../../docs/codes/fulfillmentstatuscodes) for possible values.
    Example: Package delivered to the receiver

  - `Packages.Type` (string)
    Order type - Club, Daily, or other as applicable
    Example: CLUB

  - `Packages.Warehouse` (string)
    See [warehouse locations](../../../../docs/codes/warehouselocations) for possible values.
    Enum: "APC01", "APC02", "COB01", "COB02", "ETC01", "MMC01", "PRB02", "PRB04", "SJU01", "TWL01", "VCX01", "WOX01"

  - `Packages.CarrierStatus` (string)
    Current carrier status code
    Example: D

  - `Packages.CarrierStatusMessage` (string)
    Status message directly from the carrier
    Example: Delivered

  - `Packages.CarrierStatusTimestamp` (string)

  - `Packages.PackageLocation` (string)

  - `Packages.GrossWeight` (string)
    Gross package weight in lbs
    Example: 22.6

  - `Packages.ShipToName` (string)
    Ship to name or company name
    Example: Jane Doe

  - `Packages.ShipToContact` (string)
    Ship to contact person name

  - `Packages.ShipToAddress` (string)
    Primary address where the package is shipped
    Example: 3010 Main Street

  - `Packages.ShipToAddress2` (string)
    Second address line where the package is shipped

  - `Packages.ShipToCity` (string)
    Example: Folsom

  - `Packages.ShipToState` (string)
    Example: CA

  - `Packages.ShipToZipCode` (string)
    Example: 95630

  - `Packages.ShipToCountry` (string)
    Example: USA

  - `Packages.PackageItems` (array)
    Items in the Package

  - `Packages.PackageItems.ItemNo` (string)
    Example: 1000000001

  - `Packages.PackageItems.Quantity` (string)
    Example: 6.00

  - `Packages.PackageItems.ReservedQuantity` (string)
    Example: 6.00

  - `Packages.PackageItems.ItemDescription` (string)
    Example: 2018 CAB FRANC NV

## Response 400:

  - `400` (unknown)
    Invalid Input Data

## Response 401:

  - `401` (unknown)
    Unauthorized

## Response 429:

  - `429` (unknown)
    Too Many Requests [... see rate-limit details](https://wineshipping-api.redocly.app/../../../../docs/infrastructure#rate-limits--quotas)

## Response 500:

  - `500` (unknown)
    Internal Server Error

