Guides

Scheduled drops

A drop is a named change window: it applies field values when it opens and reverts them when it closes — a weekend sale price, a launch-day title, a limited collection description. Three reads answer what is scheduled, what each drop will change, and what will change on one entity.

The drop model

A drop carries a schedule and a set of changes. Each change targets one field on one entity, on one store: it records the target_value the drop will apply and the captured_value it saved beforehand, which is restored on revert. Apply and revert each have their own status — and, when they failed, the reason.

List the account's drops

GET/api/v1/dropspim:read

Every scheduled change window with its aggregates; the per-change payload is on the detail read. Bounded by the account, so next_cursor is always null.

curl -s https://api.peak-pim.com/api/v1/drops \
  -H "Authorization: Bearer pk_live_..."

{"data": [
  {"id": "b7e1...", "name": "Summer sale", "state": "scheduled",
   "starts_at": "2026-08-01T08:00:00Z", "ends_at": "2026-08-04T08:00:00Z",
   "next_fire_at": "2026-08-01T08:00:00Z", "created_at": "2026-07-20T14:02:11Z",
   "change_count": 42, "entity_count": 21, "failed_change_count": 0}
], "next_cursor": null}

Field	Meaning
`state`	Where the drop stands in its lifecycle
`starts_at` / `ends_at`	When the window opens and closes
`next_fire_at`	The next scheduled transition
`change_count` / `entity_count`	How many field changes, across how many entities
`failed_change_count`	Changes whose apply or revert failed — the number a monitor watches
`last_error`	The most recent error, when there is one

Get one drop, with every change

GET/api/v1/drops/{id}pim:read

The detail read adds changes[] — one row per field change, per entity, per store:

{"id": "b7e1...", "name": "Summer sale", "state": "scheduled", ...,
 "changes": [
   {"id": "f09a...", "entity_id": "9c1d...",
    "store_id": "a1b2...", "store_domain": "acme-us.myshopify.com",
    "field_key": "price",
    "target_value": "99.00",
    "captured_value": "129.00",
    "captured_at": "2026-07-20T14:02:12Z",
    "apply_status": "pending",
    "revert_status": "pending"}
 ]}

target_value is what the drop will write when the window opens.
captured_value is what was there before — the value restored when the window closes.
apply_status / revert_status track each half independently; apply_error and revert_error carry the reason when one failed.

What will change on one entity

GET/api/v1/products/{id}/dropspim:read

GET/api/v1/variants/{id}/dropspim:read

GET/api/v1/collections/{id}/dropspim:read

The drops that will change this entity, each narrowed to the changes that touch it. For a product, that includes changes targeting its variants. This is the read for "what is scheduled to change on this item, and when" — without scanning every drop. next_cursor is always null.

curl -s https://api.peak-pim.com/api/v1/products/0e8f.../drops \
  -H "Authorization: Bearer pk_live_..."

What to build on this

A change calendar — list drops, order by starts_at, and show merchants what fires next (next_fire_at).
A drop monitor — poll the list and alert when failed_change_count rises; the detail read names the failing change and its apply_error or revert_error.
Pre-sync awareness — before overwriting a price in an external system, check the entity's drops: a value that looks wrong may be a sale window that is currently open.

The MCP equivalents

Tool	Arguments	Answers
`list_drops_v1`	—	The account's drops with their aggregates
`get_drop_v1`	`id` required	One drop with every change it carries, including apply/revert status and failure reasons
`list_master_drops_v1`	`id` required	The drops that will change one item (or its variants), narrowed to the changes that touch it

"What is scheduled to change on product Trail Runner 2, and when?"
"Did any changes in the Summer sale drop fail to apply?"

Drops reference — the full field tables.
Monitor publishes — the same alerting posture for ordinary publishes.