Home
Preorders

Offer

The preorder offer (selling plan) resource: CRUD, lifecycle, schedule, discard/restore.

A preorder offer is the top-level entity merchants configure. It carries everything from deposit configuration to widget copy, and attaches to a set of product variants. v2 splits the surface into:

  • CRUD — list / read / create / update / discard / restore.
  • Lifecycle — enable / disable / schedule / unschedule.
  • Capabilities — twelve sub-groups for each configuration concern. See Offer capabilities.

Path prefix: /preorders/offers

CRUD

List offers

GET /preorders/offers

Returns paginated offers in the shop, newest first. The response key is offers:

{
  "offers": [ { "id": "uuid", "name": "Spring Drop", "...": "..." } ],
  "meta": { "total_count": 12, "page": 1, "per_page": 25, "total_pages": 1 }
}
ParamTypeDefault
pageinteger1
per_pageinteger25

Aliases: "list offers", "show all offers", "preorder offers", "all preorders"

Read an offer

GET /preorders/offers/:id

Returns the full offer including a capabilities block summarizing every capability's current state.

Create an offer

POST /preorders/offers
Body fieldRequiredNotes
namenoMerchant-facing name (defaults to "Preorder")
internal_namenoSlug/reference (defaults to name)

Capability settings are configured after creation via their respective capability actions — there is intentionally no kitchen-sink create body.

Returns: 202 Accepted with the new offer (like every v2 write — see Errors & Responses).

Update top-level fields

PATCH /preorders/offers/:id

For only the fields not owned by a capability — name and internal_name.

Notes: everything else lives on a capability. Settings and toggles go through the capability's PATCH; side-effectful operations have named POST actions. See Offer capabilities.

Discard (soft-delete)

POST /preorders/offers/:id/discard

Aliases: "delete", "remove", "archive", "trash", "soft delete" Notes: Recoverable indefinitely via restore. Discarded offers are never hard-deleted.

Restore

POST /preorders/offers/:id/restore

Aliases: "undelete", "undiscard", "undo delete", "bring back" Notes: Variant attachments and metafields are not auto-restored. Re-attach via the Products capability.

Lifecycle

The lifecycle actions are intent-bearing wrappers around state changes that have side effects on inventory policy and Shopify selling-plan-group sync.

Enable

POST /preorders/offers/:id/enable
Body fieldTypeDefaultNotes
update_inventory_policybooleanfalseIf true, flips attached variants' inventory_policy to CONTINUE
variant_idsarrayall attachedRestrict the inventory-policy flip to a subset of variants

Aliases: "turn on", "activate", "launch", "go live", "start offer" Notes: Variants are left at their existing inventory policy unless update_inventory_policy: true is passed. The flip delegates to products/bulk_toggle_inventory_policy.

Disable (pause)

POST /preorders/offers/:id/disable
Body fieldTypeDefaultNotes
update_inventory_policybooleanfalseIf true, flips attached variants' inventory_policy back to DENY
variant_idsarrayall attachedRestrict the inventory-policy flip to a subset of variants

Aliases: "pause", "turn off", "deactivate", "stop offer", "end preorder", "disable and stop overselling", "close out preorder"

Schedule

POST /preorders/offers/:id/schedule
Body fieldTypeNotes
startISO 8601 stringOptional
endISO 8601 stringOptional

Aliases: "set schedule", "schedule launch", "set start date", "set end date", "schedule offer" Notes: Does not auto-enable the offer. The storefront reads the schedule live.

Unschedule

POST /preorders/offers/:id/unschedule

Aliases: "clear schedule", "remove schedule", "no schedule", "unschedule offer"

Clears both the start and end of the schedule window.

Capability surface

Every other action on an offer is grouped under one of twelve capabilities — see Offer capabilities for the full tables. Each capability has:

  • a Read action (GET the capability's current state)
  • an Update action (PATCH, deep partial) — the home of all settings and boolean toggles
  • named POST actions only where an operation has side effects beyond writing settings

(Translations is the one exception: it has no PATCH — translation writes are keyed set / unset / set_many actions.)

Built withSourcey