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).

Product

Returned by sw.products.get/list/search; accepted by sw.products.save. 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

Order

Returned by sw.orders.get/list; accepted by sw.orders.save (which merges onto 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. 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. 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.

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:

⚠️ For the *.calculate hooks the engine reads back only your modifications to ctx.data (the diff), so you must mutate the payload's options / tax in place — returning a value does nothing. 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:

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.

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