Package

Overview

A Package is the delivery unit beneath a Media Buy: 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 before parsing it for anything
`budget`	number	Budget allocated to this package — gross (fee-inclusive), like every buyer budget. See 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 below). Storefront-minted ids follow this shape:

sf_pkg_<storefrontMediaBuyId>_<N>

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 resolves that directly, no seller-side export needed. Match on productName plus endTime (or pacingPeriod.label), then take packageId:

curl https://api.interchange.io/api/v2/buyer/media-buys/mb_ETBn4gJ9Wu/packages \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

{
  "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

Meta property coverage

Meta Audience Network can deliver outside properties owned by Meta, and Meta does not provide a complete publisher-property roster during product discovery. Standard AdCP 3.1 Meta products therefore use an explicit, closed set of the advertised Facebook and Instagram placements rather than allowing Meta to expand delivery into undisclosed properties. Buyers enrolled in Interchange’s authenticated candidate AdCP 3.2 path can retain Advantage+ Placements. Those products declare property_coverage.disclosure: partial, set property_targeting_allowed: false, and name the known Facebook and Instagram properties without claiming they are exhaustive. The same trusted contract is required again when the package is created; a candidate product ID cannot be submitted through an ordinary 3.1 call. Explicit Facebook or Instagram placement selections remain complete and support placement-level delivery reporting.

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 for mode-by-mode examples.

Example: three periods → three packages per product

{
  "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:

{
  "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":

{
  "mediaBuys": [
    {
      "action": "update",
      "mediaBuyId": "mb_abc123",
      "packages": [
        { "packageId": "sf_pkg_sf_mb_1783618937177_43ycbp7b_1", "budget": 15000, "pacing": "even" }
      ]
    }
  ]
}

Get media buy packages

Resolve a description (“the display package ending 2026-08-11”) to a packageId

Media Buy

The parent ADCP transaction that spawns packages

Pacing periods

Time-windowed spend intensity that multiplies products into packages

Campaign

The parent media plan

Getting Started

Advertisers

Campaigns

Product Discovery

Webhooks

Creatives

Signals & Brand

Audiences & Inventory

Measurement & Conversions

Reporting & Activity

Planning & Governance

Connections

Account & Billing

Overview

Where a package sits in the hierarchy

Per-package fields

Package identity and the id numbering scheme

Going from a description to a packageId

Packages without a recorded flight window

Pacing strategies

Delivery metrics

Meta property coverage

How pacing periods create packages

Example: three periods → three packages per product

Cancel a single package

Get media buy packages

Media Buy

Pacing periods

Campaign

​Overview

​Where a package sits in the hierarchy

​Per-package fields

​Package identity and the id numbering scheme

​Going from a description to a packageId

​Packages without a recorded flight window

​Pacing strategies

​Delivery metrics

​Meta property coverage

​How pacing periods create packages

​Example: three periods → three packages per product

​Cancel a single package

​Related concepts

Get media buy packages

Media Buy

Pacing periods

Campaign

Overview

Where a package sits in the hierarchy

Per-package fields

Package identity and the id numbering scheme

Going from a description to a packageId

Packages without a recorded flight window

Pacing strategies

Delivery metrics

Meta property coverage

How pacing periods create packages

Example: three periods → three packages per product

Cancel a single package

Related concepts