Peak PIMDevelopers

Operations

Drops

A drop is a scheduled change window: a named period that applies field values when it opens and reverts them when it closes. These reads answer what is scheduled, what each change will do, and how the last run went.

List drops

GET/api/v1/dropspim:read

Every scheduled change window in the account, with its aggregates. The per-change payload is on the detail read — list rows omit changes. Bounded by the account, so next_cursor is always null. 

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

Response — 200

{
  "data": [
    {
      "id": "e7c3a9f1-2b8d-4e6a-9c4f-1d5b8a2e7c93",
      "name": "Summer sale",
      "state": "scheduled",
      "starts_at": "2026-08-01T07:00:00Z",
      "ends_at": "2026-08-15T07:00:00Z",
      "next_fire_at": "2026-08-01T07:00:00Z",
      "created_at": "2026-07-20T14:32:11Z",
      "change_count": 48,
      "entity_count": 24,
      "failed_change_count": 0
    }
  ],
  "next_cursor": null
}

Get one drop

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

One drop with every change it carries, including each change's apply/revert status and, when it failed, the reason.

Response — 200

{
  "id": "e7c3a9f1-2b8d-4e6a-9c4f-1d5b8a2e7c93",
  "name": "Summer sale",
  "state": "scheduled",
  "starts_at": "2026-08-01T07:00:00Z",
  "ends_at": "2026-08-15T07:00:00Z",
  "next_fire_at": "2026-08-01T07:00:00Z",
  "created_at": "2026-07-20T14:32:11Z",
  "change_count": 48,
  "entity_count": 24,
  "failed_change_count": 0,
  "changes": [
    {
      "id": "a1d8f2c6-9e4b-4c7a-8b3d-6f2e9c5a1d84",
      "entity_id": "5b2e9c1a-7d4f-4a8b-9e6c-3f1d8a5b2c70",
      "store_id": "1e8e4c2a-9f3b-4d7c-8a5e-6b2d9c1f7a30",
      "store_domain": "acme-eu.myshopify.com",
      "field_key": "price",
      "target_value": "39.00",
      "captured_value": "49.00",
      "captured_at": "2026-07-20T14:32:11Z",
      "apply_status": "pending",
      "revert_status": "pending"
    }
  ]
}

List an entity's scheduled changes

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 — the product read also covers changes to the product's variants. Same {"data": […], "next_cursor": null} list shape, with changes present on each drop but filtered to the entity. Bounded by the account's drops, so next_cursor is always null. An unknown entity id answers 404 not_found; an entity with no scheduled changes answers an empty list.

The drop and change shapes

FieldTypeDescription
id / nameuuid / stringThe drop's identity.
statestringWhere the drop stands in its lifecycle.
starts_at / ends_atdate-timeThe window. Only starts_at is guaranteed; ends_at may be absent.
next_fire_atdate-timeThe next time the scheduler will act on this drop.
created_atdate-timeWhen the drop was created.
last_errorstringThe most recent run error, when there was one.
change_count / entity_count / failed_change_countintegerAggregates over the drop's changes.
changesarrayPresent on the detail read (and the per-entity reads); omitted on list rows.

Each change is one field change on one entity, on one store:

FieldTypeDescription
iduuidThe change's id.
entity_iduuidThe entity the change targets.
store_id / store_domainuuid / stringThe store the change applies on.
field_keystringThe field being changed.
target_valuestringThe value the drop will apply.
captured_valuestringThe value captured before applying, restored on revert.
captured_atdate-timeWhen the value was captured.
apply_status / apply_errorstringHow the apply went; the reason when it failed.
revert_status / revert_errorstringHow the revert went; the reason when it failed.
Watch failed_change_count, then drill in.

A monitoring integration polls the list, and only fetches a drop's detail when failed_change_count is non-zero or last_error is set — then reads apply_error / revert_error per change. See the scheduled drops guide.

Notes