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, _rinven_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, "instructions": string, "hours": string } — all optional.

Tracking

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

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():