Entity & Context Reference

This is the field-level companion to Plugins.md. Plugins.md documents what the bridges and hooks do; this document documents the exact shape of the data they hand you — the entity records returned by sw.products / sw.orders / sw.customers / sw.coupons / sw.records, and the ctx object your hooks, widgets, routes, and tasks receive.

Conventions used throughout:

• Empty fields are omitted. When a field is empty it is absent from the record entirely — don't assume a key exists. Read defensively with optional chaining or defaults: const tags = product.tags || [].
• Some fields are never exposed to plugins — a customer's password and the internal shop-scoping id are invisible. Scoping is implicit (every sw.* op runs within the current shop), so you never set or read it.
• Money is integer cents (price: 2499 = $24.99). Never floats.
• Ids are integers and auto-allocated on first save (pass no id to create).
• Timestamps are RFC3339 strings (created, updated) set by the platform; they're read-only — writing them back on save() has no effect.
• A ✎ marks a field you can set via save(). Unmarked fields are platform-managed (read-only, or computed in a before-save hook).
• save() patches, it doesn't replace — see Saving with save().

Saving with save()

sw.products.save / sw.orders.save / sw.customers.save / sw.coupons.save are patches, not replacements. Pass an id and the stored record is loaded first, then only the fields you sent are overlaid on it — so a two-field update never clobbers the rest of the record:

sw.products.save({ id, stock: 4 });   // name, price, images, variants … all untouched

Omit id and you get a create instead: with nothing to overlay, unsent fields take their defaults.

meta merges by key

meta follows the same rule one level deeper — keys you don't send survive, keys you do send are replaced whole. There is no deep merge inside a key's value. Starting from meta = { a: 1, b: "keep", nested: { x: 1, y: 2 } }:

To patch one field of a nested object, spread the stored one back in:

const p = sw.products.get(id);
sw.products.save({ id, meta: { nested: { ...(p.meta?.nested || {}), x: 9 } } });

Removing a key. Because unsent keys survive, you cannot delete a meta key by dropping it from the object and saving the record back — the stored key is still there afterwards:

const p = sw.products.get(id);
delete p.meta.stale;
sw.products.save(p);                 // ✗ no-op: `stale` survives the merge

Set the key to null instead. It stays present with a null value — which reads as absent to any truthiness check, and, for a _-prefixed key, drops its entry from the queryable index:

sw.products.save({ id, meta: { stale: null, _erp_id: null } });   // ✓

Send meta: null to clear the whole map at once.

Product

Returned by sw.products.get/list/search; accepted by sw.products.save (which patches the stored product). Also the shape of ctx.data in product.before_save / product.after_save / product.*_delete.

Option

{ "name": "Size", "values": ["S", "M", "L"] }

Variant

PriceTier

{ "min_qty": 10, "price": 1999 } — applies when ordered qty ≥ min_qty; the highest matching min_qty wins. price in cents.

Attribute

{ "name": "Material", "value": "Cotton", "extra": { "facet": true } } — extra is optional (facet, hidden, …).

ProductSubscription

SubscriptionPlan

anchor must match the cadence: only a weekly plan can use day_of_week, and only a monthly/quarterly/yearly plan can use day_of_month. Saving a mismatched pair is rejected.

SubscriptionBounds

The range a single billing cycle may move within, for a plan whose amount isn't the same every time — weekly music lessons, where some months have four and some have five. Your subscription.before_renew handler decides each cycle's actual numbers; these bounds are what the store owner agreed those numbers may be.

An axis moves only if it has a maximum. A floor on its own doesn't authorize anything, so min_qty without max_qty (or min_price without max_price) is rejected rather than quietly ignored. Setting only quantity bounds leaves the price locked, and vice versa — nothing becomes writable by accident.

These are snapshotted onto each contract when a customer subscribes, so editing a plan's bounds later changes what new subscribers agree to, never what existing ones already agreed to.

A store owner can adjust a live subscription's bounds from the admin; a plugin cannot. sw.subscriptions.update has no bounds key and never will — these are the limits your own per-cycle amounts are checked against, so a plugin that could widen them would be marking its own homework. The asymmetry is deliberate rather than an oversight: a store owner can already set any quantity or price directly, so editing the limits grants them nothing new, and it saves cancelling and re-subscribing a customer whose arrangement changed.

Order

Returned by sw.orders.get/list; accepted by sw.orders.save (which patches the stored order — see Plugins.md → Orders). Also the shape of ctx.data in order.before_save / order.after_save / order.*_delete.

OrderItem

OrderCustomer

{ "id": integer, "name": string, "email": string, "phone": string } — id/phone absent when empty; email is lowercased on save.

OrderPayment

OrderTotals

{ "subtotal", "tax", "shipping", "discount", "total" } — all integer cents. tax/shipping absent when 0.

OrderShippingMethod

ShippingPickupDetails

{ "address": string, "location": Address, "instructions": string, "hours": string } — all optional.

address is the one-line form shown to the shopper (checkout, the ready-for-pickup email). location is the same counter as a structured Address — line1, line2, city, state, zip, country — and it is what decides tax: an order collected in store has no delivery address, so its tax is rated at the counter. A location needs at least a country to be used; without one the store falls back to the shopper's address, and a store that filled in nothing but address keeps behaving exactly as before.

Leaving address blank fills it in from location on save, so a store only has to enter the place once. Set it to override the wording shown to shoppers.

Tracking

{ "carrier": string, "number": string, "url": string } — url optional.

Leave url out and a major carrier (USPS, UPS, FedEx, DHL, Canada Post, Purolator, Royal Mail, Australia Post, OnTrac, DPD, GLS, NZ Post) gets its standard tracking link, matched on the carrier name however it is capitalized or spaced. So url is filled in whenever the carrier is one of those, and what you write to it is an override: set it for a carrier not on that list, or to point somewhere other than the carrier's own page. An override you save comes back exactly as written; the standard link is worked out fresh each read, so a carrier changing its tracking address doesn't leave old shipments pointing at a dead page.

PaymentAdjustment

{ "label": string, "amount": integer } — signed cents (negative = discount). Pushed by the payment.calculate_adjustment hook.

OrderRefund

Customer

Returned by sw.customers.get/list; accepted by sw.customers.save (which patches the stored customer). Also the shape of ctx.data in customer.before_save / .after_save / .*_delete.

No shop_id, no password. A customer's password and the internal shop-scoping id are never exposed to a plugin. Scoping is implicit (all sw.customers ops run within the current shop).

CartItem

{ "product_id": integer, "shop_id": integer, "name": string, "price": integer, "image": string, "qty": integer, "set": object, "plan": string } — price in cents; set/plan/image optional.

Address

Shared by orders and customers.

{ "name", "line1", "line2", "city", "state", "zip", "country", "phone" } — all strings; line2/phone and any empty field are omitted. country is ISO 3166-1 alpha-2.

Coupon

Returned by sw.coupons.get/list; accepted by sw.coupons.save (which patches the stored coupon). Also ctx.data in coupon.before_save / .after_save / .*_delete.

Keyed by a numeric id, not the code. To resolve a typed code, use sw.coupons.list({ filters: { code: "SAVE10" } }). The shop-scoping id is not exposed.

Subscription

A customer's recurring contract: what renews, how often, and where it stands. Each billing cycle mints a new order (the invoice) while this record persists across all of them.

Returned by sw.subscriptions.get/list. Fields marked ✎ are accepted by sw.subscriptions.update — everything else is read-only, maintained by the platform as the contract bills. There is no save/delete; see Plugins.md → Subscriptions (sw.subscriptions).

SubscriptionError

SubscriptionHold

A hold is not a status: the contract keeps whatever status it had, stays intact, and is simply no longer scheduled. It resumes when the merchant releases it from the admin — the customer is never cancelled over a problem they couldn't fix.

Custom records

Records declared under a plugin's custom_records manifest entry, accessed via sw.records.<type>.get/list/save/delete. Their shape differs from the built-ins. A record is returned flattened — the declared fields sit at the top level alongside the envelope keys, not nested under a data object:

const r = sw.records.demo_record.save({ title: "Hello", value: 123, enabled: true });
// r === {
//   id: 42,
//   kind: "demo_record",
//   created: "2026-07-02T…",
//   updated: "2026-07-02T…",
//   title: "Hello",      // ← declared fields, flat
//   value: 123,
//   enabled: true
// }

In record.<kind>.* hooks, ctx.data is this same flattened record.

Shop projection (ctx.shop)

Wherever a plugin is handed the shop — ctx.shop in routes/tasks, ctx.widget.shop in widgets, and ctx.data.shop in the checkout/cart/payment hooks — it is an allowlisted projection (only the fields below are exposed; everything else on the shop is withheld):

The ctx object

Hook ctx

Passed to every module.exports["<hook>"] = function (ctx) { … }:

There is no ctx.shop or ctx.plugin on the generic hook ctx — only ctx.shop_id. The shop object appears as ctx.data.shop on the checkout/cart/payment hooks that include it (see the table).

What ctx.data holds per hook

The CRUD hooks carry the full entity (the shapes above) plus ctx.old_data. The other hooks carry a purpose-built payload — the columns below name its shape; see the linked Plugins.md sections for each hook's behavior and expected return.

Entity CRUD — ctx.data = the entity, with ctx.old_data:

Commerce / calculation — see Plugins.md → Checkout & Cart Hooks and Payment Gateway Hooks:

The storefront cart→checkout hooks below (cart.calculate_prices, coupon.validate, shipping.calculate, tax.calculate, checkout.before_create) also receive ctx.customer — the logged-in shopper's Customer record (absent for guests) — so a calculation can vary by the signed-in customer (B2B price_level, saved-method payment_gateway, etc.). Secret fields are never exposed.

⚠️ For the *.calculate hooks the engine reads back only your modifications to ctx.data — you must assign to its fields (set ctx.data.tax, replace ctx.data.options); returning a value does nothing. To change options, reassign the whole array — ctx.data.options = ctx.data.options.concat([newOpt]) (or .filter(...), or [...ctx.data.options, newOpt]). A bare ctx.data.options.push(newOpt) is silently dropped (editing a field of an existing option in place, e.g. ctx.data.options[0].price = X, does take effect — only appending via push is the trap). See Modifying vs. preventing.

Render / email / SEO / search — see Plugins.md → Template Render Hooks, Email Hooks, Sitemap & Robots Hooks, Search Provider Hooks:

Lifecycle / async — see Plugins.md → Plugin Lifecycle Hooks, Container Job Hook, In-App Purchases:

Modifying vs. preventing

• Modify an entity/payload by mutating ctx.data in place. The engine diffs ctx.data before/after your handler and merges changed top-level keys back (last-writer-wins across plugins). Returning a value is ignored.
• Prevent the platform's default action by throw — either a string, or an object throw { error: "message", redirect_url: "/x" } (the structured throw is surfaced to the platform). This marks the event prevented and, for *.before_save, fails the operation.
• ctx.stop(reason?) is the clean alternative to throw: "I've handled this, skip the built-in behaviour" — no error is logged. Use it for e.g. email.send when your plugin delivered the mail itself.

Widget ctx

Passed to a widget's fetch(ctx) export (see Plugins.md → Dashboard Widgets):

ctx.widget:

ctx.request

The visitor request, exposed to fetch routes, widgets, and storefront-dispatched hooks. Sanitized — auth, cookie, and tracing headers are stripped, and only trusted, canonical request signals are exposed.

ctx.request = {
  method:  "GET",
  url:     "https://shop.example.com/product/x?ref=abc",
  path:    "/product/x",
  proto:   "https",
  headers: { /* sanitized; see below */ },
  query:   { "ref": "abc" }        // first value per key
}

Geo / IP / bot signals live inside headers (there is no top-level geo/ip object), only populated in production:

A theme sees these same values as the storefront geo binding, field for field (Themes.md → "Visitor location").

Body (fetch routes + widgets only — hooks get no body accessors): ctx.request also carries body (streaming reader), and text(), json(), arrayBuffer(), formData(). The body is consume-once — buffering methods share a single read, and streaming vs. buffering are mutually exclusive.

ctx.settings

The plugin's merged effective settings: the merchant's saved values overlaid on the manifest settings[].defaults. So a setting the merchant never touched still reads as its declared default. {} when the plugin declares no settings.

Caveat — bg tasks & lifecycle hooks get raw settings. In sw.task.bg closures, named run/action scripts, and the plugin.activate/deactivate/ uninstall hooks, ctx.settings is the saved settings only — manifest defaults are not merged in, so a defaulted-but-unsaved key can be undefined. Merge defaults yourself there, or read settings inside a hook/route/render path.

ctx.dev

true while the plugin runs as your live local copy during a dev session (the code you're editing, synced from your machine); false once it's installed on a shop from the marketplace. Present on every ctx — hooks, fetch routes, widgets, lifecycle hooks, and background/scheduled runs.

Use it to skip a production-only side effect while testing — most commonly a step that's gated to marketplace installs and would error from a dev copy:

if (!ctx.dev) {
  sw.payments.linkAccount(accountId); // marketplace-only; skip during local dev
}

Scheduled / background-task ctx

Scripts run outside the hook path (scheduled run, actions, sw.task.bg) also get a ctx, plus the always-on ctx.settings / ctx.plan / ctx.shop_id / ctx.dev / ctx.timeoutRemaining():