> ## Documentation Index
> Fetch the complete documentation index at: https://docs.interchange.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Package
> One product per pacing period beneath a media buy — carries its own budget, pacing strategy, bid price, and optimization goals
## Overview
A **Package** is the delivery unit beneath a [Media Buy](/v2/buyer/campaigns/media-buys): one package per product, multiplied by the number of pacing periods. Packages are created when a media buy executes — like media buys, they are not directly creatable. Each package carries its own budget, pacing strategy, bid price, and optimization goals, and reports its own delivery metrics.
Packages are spawned at execution. A product selected on a `DRAFT` campaign becomes one package per pacing period once the campaign executes and the media buy submits to ADCP.
### Where a package sits in the hierarchy
```
Campaign
└── Media Buy (one per sales agent)
└── Package (one per product per pacing period)
└── Delivery (impressions, spend, clicks)
```
## Per-package fields
| Field | Type | Notes |
| ------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `packageId` | string | Stable for the life of the package. Pass it when updating or pausing a single package. Opaque: see [Package identity and the id numbering scheme](#package-identity-and-the-id-numbering-scheme) before parsing it for anything |
| `budget` | number | Budget allocated to this package — gross (fee-inclusive), like every buyer budget. See [Budgets and fees](/v2/concepts/budgets-and-fees) |
| `pacing` | enum | Pacing strategy: `even`, `asap`, `front_loaded` |
| `bid price` | number | Per-package bid |
| `optimizationGoals` | array | Inherited from the media buy at execution (event- or metric-based) |
## Package identity and the id numbering scheme
Every package carries a `packageId` that is stable for the life of the package, and it is what you pass in `packageIds` or `packages[]` when you cancel or update one package (see [Cancel a single package](#cancel-a-single-package) below). Storefront-minted ids follow this shape:
```
sf_pkg__
```
`N` is a **one-based position across the whole dispatch**, not a period number, and it is not stable across media buys. On a buy with 2 products over 3 pacing periods, `_1` through `_6` cover both products: the first three belong to one product, the next three to the other.
Treat `packageId` as opaque. Never parse the trailing number to find a package's pacing period, and never assume the same suffix means the same period across two different media buys. Read `pacingPeriod.index` and `pacingPeriod.label` on the package itself instead.
On the first product of a buy the suffix happens to line up with the period index, which makes a parsing shortcut look correct when you spot-check it. It is a coincidence of the ordering: on the second product the same suffix is off by the number of periods.
### Going from a description to a packageId
A buyer or their agent typically has a description, not an id: "the display package ending 2026-08-11." [Get media buy packages](/v2/buyer/campaigns/tasks/get-media-buy-packages) resolves that directly, no seller-side export needed. Match on `productName` plus `endTime` (or `pacingPeriod.label`), then take `packageId`:
```bash theme={null}
curl https://api.interchange.io/api/v2/buyer/media-buys/mb_ETBn4gJ9Wu/packages \
-H "Authorization: Bearer $SCOPE3_API_KEY"
```
```json theme={null}
{
"mediaBuyId": "mb_ETBn4gJ9Wu",
"isPaced": true,
"packageCount": 2,
"packages": [
{
"packageId": "sf_pkg_sf_mb_1783618937177_43ycbp7b_1",
"productId": "prod_display_300x250",
"productName": "Display Run of Site",
"status": "active",
"pacingPeriod": { "index": 1, "label": "Week 1" },
"startTime": "2026-08-01T00:00:00Z",
"endTime": "2026-08-07T23:59:59Z",
"budget": 5000,
"budgetCurrency": "USD",
"pacing": "even"
},
{
"packageId": "sf_pkg_sf_mb_1783618937177_43ycbp7b_2",
"productId": "prod_display_300x250",
"productName": "Display Run of Site",
"status": "active",
"pacingPeriod": { "index": 2, "label": "Week 2" },
"startTime": "2026-08-08T00:00:00Z",
"endTime": "2026-08-11T23:59:59Z",
"budget": 5000,
"budgetCurrency": "USD",
"pacing": "even"
}
]
}
```
Both packages are the same product, so `productName` alone does not pick one. The `endTime` does: the second entry ends `2026-08-11T23:59:59Z`, so its `packageId` (`sf_pkg_sf_mb_1783618937177_43ycbp7b_2`) is the one to send. Match on the field, not on the trailing number.
### Packages without a recorded flight window
`startTime`, `endTime`, and `pacingPeriod` are absent on packages created before the platform started retaining this identity, and on any media buy that was never split across periods. Expect this to be the common case on buys that are already live: no package created before the change carries a period, and most carry no window either. The platform now keeps the flight window it requested even when the seller's response omits it, but it cannot reconstruct one for a package already stored without it, so the gap is permanent for those packages.
The periods themselves are still readable on the campaign, including each period's label and dates. What is missing is only the link from a package to its period.
For those packages, `productName` plus `budget` sometimes narrows it to one. Often it will not: a schedule that gives several periods the same budget gives their packages identical budgets, so same-product siblings come back indistinguishable, and nothing this API returns separates them. Those packages cannot be addressed individually, and the seller is the only remaining route. Check for the presence of `startTime`/`endTime` before matching on them, and treat two identical entries as unresolved rather than picking one: pausing the wrong period is worse than asking.
### Pacing strategies
| Strategy | Behavior |
| -------------- | --------------------------------------------- |
| `even` | Spread spend evenly across the package window |
| `asap` | Spend as fast as inventory allows |
| `front_loaded` | Weight spend toward the start of the window |
## Delivery metrics
Delivery metrics roll up per package:
* `impressions`
* `spend` — gross (fee-inclusive), stated at the fee terms locked on the parent media buy, so it compares directly against the package's budget. Packages under a legacy media buy created before fee terms were locked report spend net, as the seller reported it
* `clicks`
## How pacing periods create packages
Each product becomes one package per pacing period. The campaign's `pacingPeriods` defines time-windowed spend intensity within the flight, in one of two modes:
* **`weight`** — relative weights (e.g. `3.0` = 3x normal); budget is distributed proportionally across periods.
* **`budget`** — an explicit dollar amount per period.
On execute, each product is split into one package per period, with budget set proportionally (weight mode) or explicitly (budget mode). **Gaps between periods are treated as pauses** — no spend, and no package covers the gap.
Pacing periods can only be modified on `DRAFT` campaigns. After execution, the package split is locked in. See the [Pacing periods guide](/v2/guides/pacing-periods) for mode-by-mode examples.
### Example: three periods → three packages per product
```json theme={null}
{
"pacingPeriods": {
"mode": "weight",
"periods": [
{ "label": "Pre-Black Friday", "start": "2026-11-01T00:00:00Z", "end": "2026-11-26T23:59:59Z", "weight": 1.0 },
{ "label": "Black Friday / Cyber Monday", "start": "2026-11-27T00:00:00Z", "end": "2026-12-02T23:59:59Z", "weight": 3.0 },
{ "label": "Holiday push", "start": "2026-12-03T00:00:00Z", "end": "2026-12-31T23:59:59Z", "weight": 1.5 }
]
}
}
```
With this configuration, every selected product produces three packages — one per period — each weighted for proportional budget.
## Cancel a single package
To cancel one package without touching the rest of its media buy, pass `packageIds` on a `mediaBuys[]` entry in `PUT /api/v2/buyer/campaigns/:id`. Resolve the `packageId` first with [Get media buy packages](/v2/buyer/campaigns/tasks/get-media-buy-packages):
```json theme={null}
{
"mediaBuys": [
{
"action": "cancel",
"mediaBuyId": "mb_abc123",
"packageIds": ["sf_pkg_sf_mb_1783618937177_43ycbp7b_2"],
"reason": "format not supported on this device mix"
}
]
}
```
You can also update a package's budget and pacing in place by passing it in the `packages[]` array with `action: "update"`:
```json theme={null}
{
"mediaBuys": [
{
"action": "update",
"mediaBuyId": "mb_abc123",
"packages": [
{ "packageId": "sf_pkg_sf_mb_1783618937177_43ycbp7b_1", "budget": 15000, "pacing": "even" }
]
}
]
}
```
## Related concepts
Resolve a description ("the display package ending 2026-08-11") to a packageId
The parent ADCP transaction that spawns packages
Time-windowed spend intensity that multiplies products into packages
The parent media plan