The Commerce plugin (plugins/commerce/) is Birkly’s content-first store: payment providers, the Commerce fieldtype, catalog, cart, checkout, orders, customers, inventory, promotions, gift cards, tax providers, shipping rate providers, and PostPurchaseRouter fulfillment — all driven by CMS entries.
Commerce 0→1 complete (P54 P3 / 1.0.29): hybrid cart + split checkout, MCP/Agent store kit, Automation commerce recipes, and ops intelligence (cohorts, fulfillment SLA, low-stock trigger). This closes the foundation path from empty site → sellable catalog → checkout → ops. Do not expect P4 features here.
In-admin docs (Commerce 1.0.57+): open Commerce → Docs for the full merchant + developer guide (grouped topics: getting started, fieldtype, catalog, tax, shipping, storefront, API, troubleshooting, and more). The same topics also appear under Help → Plugin extensions → Commerce.
Activate Commerce under Settings → Plugins, configure a payment provider under Commerce → Settings → Connections, add the Commerce fieldtype to collections, and model products with fulfillment (ship, deliver, register, gift_card, none) plus one or more purchase_options (one-time and/or recurring on the same entry). Use variant sub-entries for SKUs. Template functions expose cart count and buy URLs on client sites.
Beginner
What Commerce does
Commerce turns Birkly entries into things you can sell: physical products, digital downloads, class tickets, memberships, and sellable gift cards — without a separate e-commerce product database. Edit content in the CMS; Commerce indexes sellable units for checkout.
Two settings on each sellable item
| Setting | Plain language |
|---|---|
| Fulfillment | What happens after someone pays (ship a box, send a download, register for a class, issue store credit, or grant access) |
| Purchase options | How they pay — e.g. €25 once or €19/month on the same product |
Catalog, inventory, and orders
| Area | Role |
|---|---|
| Catalog | Read model of sellable CMS entries (edit the entry, then rebuild the index if needed) |
| Inventory | Ledger system of record for countable stock |
| Orders | Commercial history with frozen money/tax snapshots from checkout |
Stock modes (Inventory): Unlimited (ignore counts) · Simple (one row per SKU) · Locations (SKU stock per warehouse).
Quick setup
- Settings → Plugins → enable Commerce.
- Open Commerce in the sidebar → Settings → Connections → add Stripe, Mollie, or another provider.
- Edit a collection schema → add field type Commerce.
- Create an entry with price, fulfillment, and purchase options.
- On your website, add a buy button using
{commerce_buy_url entry_id collection}(orcommerce-storefront.js— see Commerce → Docs → Storefront & cart). - Read Commerce → Docs for tax modes, shipping, hybrid cart, and project integration checklists.
Variants (sizes, options)
For products with multiple SKUs (size, grind, color):
- Create a parent product entry with photos and description.
- Add a variants sub-collection.
- Each variant sub-entry gets its own Commerce field (price, SKU, stock).
After payment
Commerce routes each order line by fulfillment:
- Ship — Manual export or EasyPost tracker/label; admin can create partial / multi-package shipments
- Deliver — secure download link emailed
- Register — attendee recorded, capacity reduced
- Gift card — store-credit codes issued (face value = unit price)
- None — tier grant or automation (memberships)
Advanced Users
Content model (v2)
{
"fulfillment": "ship",
"tax_class": "standard",
"weight_grams": 250,
"purchase_options": [
{ "id": "once", "label": "Buy once", "billing": "one_time", "price_cents": 1499, "currency": "eur" },
{ "id": "sub", "label": "Subscribe", "billing": "recurring", "interval": "month", "price_cents": 1299, "currency": "eur" }
],
"quantity_available": null,
"sku": "SKU-250G"
}quantity_available is a catalog projection of Inventory Available (or null for unlimited / capacity for register). Inventory is the ledger SoR for countable SKUs. tax_class defaults to standard; rates come from Settings → Tax. weight_grams is required on ship lines when EasyPost live rates are enabled.
PostPurchaseRouter — idempotent handler keyed on order_id + line; fires typed automation triggers including commerce_physical_fulfilled, commerce_digital_delivered, commerce_event_registered, commerce_gift_card_issued, commerce_subscription_started (commerce_membership_started is a deprecated alias). Shipments also fire commerce_shipment_created / commerce_order_shipped when notify is enabled; EasyPost tracking fires commerce_tracking_updated.
Admin areas (Commerce 1.0.29)
| Tab | Purpose |
|---|---|
| Dashboard | Revenue, AOV, new vs returning, first-order cohorts, needs-shipping / SLA breaches, avg fulfillment time, top products, affiliates |
| Orders | Paid orders, fulfillment state, frozen money/tax lines; Draft orders / Quotes include a cart-free editor |
| Customers | Email-keyed profiles, CSV import, order/subscription timeline; optional User Management link; no passwords |
| Catalog | Indexed read model of sellable CMS entries |
| Inventory | Stock ledger: Unlimited, Simple, or Locations; low-stock threshold feeds commerce_low_stock |
| Subscriptions | Recurring purchases and lifecycle actions |
| Discounts | Promotions v2: usage limits, min purchase, date window, free shipping, stack rules |
| Gift Cards | Admin-issued store credit; sellable products use fulfillment gift_card |
| Settings | Connections, General (incl. fulfillment SLA hours), Fieldtypes, Mappings, Import & migrate, Shipping, Tax, Fulfillment, Activity, Documentation |
Differentiation (P3 / 1.0.29)
- Hybrid cart: mix ship + deliver + register + subscribe; split checkout by billing group — see Hybrid cart and plugin
help-hybrid-cart. - Store kit: MCP/Agent playbook topic
commerce-store-kitseeds products + checkout — see Store kit. - Automation recipes: import post-purchase, dunning, low-stock, shipped starters — see Commerce recipes.
- Ops intelligence: Dashboard cohorts + fulfillment SLA (
commerce_fulfillment_sla_hours, default 48) +commerce_low_stock— see Analytics.
Provider honesty (P2, still current)
- Tax: Manual or Stripe Tax (orthogonal to charge PSP). Frozen
tax_lineson paid orders. Optional B2B reverse charge viavat_id— no live VIES. - Shipping rates: Manual zones or EasyPost live quotes; fallback to zones on live failure; weight required for EasyPost.
- Fulfillment: Manual / Export (default) or EasyPost (push + tracking webhook). ShipStation is an internal stub and is not offered.
- Draft orders: Admin editor under Orders — create/edit lines without a cart, preview tax/shipping, save & send accept link.
- Import & migrate: Shopify cutover, CSV, and live product import adapters (Beta). Legacy Shop / Events migration appears only when detected.
- Gift cards: Admin-issued and sellable products (
fulfillment: gift_cardissues codes on pay).
Plugin docs shelf: register_plugin_docs('commerce', …) ships plugins/commerce/docs/ for AI, Admin Help, and MCP (birkly://docs/plugin/commerce).
Public API: /api/index.php?route=commerce — cart get/add/update/remove/checkout; cart payload may include split_required / groups[]; checkout selects purchase_option_id (and group_key + checkout_session_id when split) and collects shipping/attendee/VAT per fulfillment.
Legacy: P6.4 flat schema (price_cents + billing) migrates to single purchase_option + inferred fulfillment.