Shop (beta)

Shop (justflows.shop) is the official e-commerce plugin, built and maintained by the Justflows team. It adds a catalog, a public /shop page, cart and checkout, orders, customers, payments, shipping, tax, discounts, and order emails. Products are ordinary CMS content of type product, so they get the block editor, translations, SEO, and search. Prices, stock, orders, and payments live in the plugin's own shop_* tables.

Install and set up#

Beta plugins are hidden behind a switch so nobody installs one by accident.

1. 1

   Allow beta installs

   Admin → Settings → Marketplace → turn on Allow installing beta plugins and themes. Until then, Shop shows a Beta badge and its Install button stays off.

2. 2

   Install and activate

   Admin → Marketplace → Shop → Install, confirm the beta warning, then Activate. You can also upload a Shop .jfpkg from Admin → Plugins.

3. 3

   Choose where commerce data lives

   Activation opens the setup guide. Keep the current Justflows database (the default), or use a separate commerce database, which is tested before you can continue. This choice is permanent: changing it later is a migration, not a setting.

4. 4

   Enter store details

   Store name, address, currency, and selling options are optional here. You can fill them in later.

5. 5

   Finish

   Shop creates its tables, the Product and Shop content types, and the storefront pages: Shop, Product detail, Product category, Cart, Checkout, Order confirmation, Customer account, and Order tracking. The Commerce section appears in the admin sidebar.

Store settings#

Admin → Plugins → Shop → Settings, also reachable from the Settings tab at the end of the Commerce menu.

Order numbers

Each new order number is prefix + format + suffix. The defaults give numbers like JF260929-A1B2. These tags work in all three parts:

Random tags take a length, for example {RANDOM_NUMBER:6} (1 to 12). Dates, week numbers, and counter resets use UTC. The counter has a start number, a step, a zero-padded length, and a reset (never, daily, weekly, monthly, or yearly). You can also schedule a one-off reset (Reset counter on, for example 2027-01-01 00:00) or tick Reset counter now.

Order numbers keep letters, digits, ., -, and _, and are at most 64 characters. If a number is already taken, the counter moves to the next free value; a format with no counter or random tag gets a random ending. Changes apply to new orders only.

Products#

Commerce → Products → new. New products start from the Product detail layout. The content editor menu shows Images, Pricing, Inventory, Shipping, Attributes, Variations, Categories, and Tags as separate entries.

• Shared across languages: SKU, prices, stock, and variations belong to the product's translation group, so every translation sells the same item. Title, excerpt, and page content are per language. Shop → Products lists the default language only; switch languages in the content editor.
• Attributes (Commerce → Attributes): select, text, color, image, button, or number. A select attribute with several values generates variation combinations. Choosing an option on the product page updates the price, SKU, and stock.
• Categories and tags (Commerce → Categories / Tags): categories can be nested. Both are assigned in the product editor.
• Visibility: public and catalog-only products appear on /shop; hidden and search-only products do not. Published products are included in site search.

Import products

Commerce → Products → Import takes CSV, JSON, or XML and detects the format. Run the preview first: it lists what will be created, updated (matched by SKU), or rejected, and writes nothing. A sample file ships as samples/products-sample.json.

title, slug, sku, price, stock, status, categories, tags, images, excerpt

Product tags in layouts

Put these tags in any text of a product layout. They are filled from the catalog on the public page: {{title}}, {{excerpt}}, {{sku}}, {{barcode}}, {{price}}, {{regular_price}}, {{sale_price}}, {{currency}}, {{stock}}, {{type}}, {{visibility}}, {{tax_class}}, {{weight}}, {{length}}, {{width}}, {{height}}, {{dimensions}}, {{attributes}}, and {{options}}. {{price}} follows the catalog tax display (see Tax).

The shop page#

Activating Shop publishes /shop, which lists published catalog products as a grid or a list. When inventory is set to hide out-of-stock products, those are left off too. A Shop page that already has its own blocks is left alone. Commerce → Shop page controls it:

Search and filters run in the browser on the products already loaded. Choosing a parent category includes its subcategories. The price filter compares the shown price, and both it and the "On sale" switch hide themselves when they cannot narrow anything. Active filters show as removable chips with Clear all. The filter state is kept in the address, so a filtered view can be shared:

/shop?category=<slug>&tag=<slug>&q=<text>&min=<n>&max=<n>&sale=1&sort=price-asc

Storefront blocks and patterns#

Shop registers these blocks in the page builder. Every field has a label and help text, and fields that do not apply to the current choice are hidden.

Product list and Related products take their products from: all products, products related to a product (most shared categories and tags first, then newest), products you pick (a searchable checklist, in the order you tick them), chosen categories (subcategories included), or chosen tags. Sort by newest, oldest, name, or price, and show up to 24. A product page never lists itself. Type rows by hand keeps manual rows.

Gallery, Buy box, Breadcrumbs, and Details accordion have a Product picker. Left empty, they follow the product page they are on. With a product picked, they show that product on any page, and Add to cart adds it.

Patterns: Product detail, Product mosaic, Product story, Product list, and Ecommerce storefront. Storefront styles (.jf-product-*) are added to /theme.css only while Shop is active. Products without a photo show the site's Product image placeholder, which you can replace under Settings → Placeholders.

Cart and checkout#

• Cart (/shop/cart) lists each product with its photo, options, unit price, and line total. Quantities can be changed or removed. The subtotal follows the catalog tax display, and checkout stays closed until every line can be sold. Product pages and the cart only show a stock count when 5 or fewer are left.
• Checkout (/shop/checkout) collects contact, shipping, and billing details, then prices delivery, tax, and discounts. Country lists follow the selling and shipping countries. Guest checkout closes when the shop requires an account.
• Signed-in shoppers start with their account email, name, phone, and last billing and shipping addresses, all editable. Placing an order saves those details to the customer record linked to their account, and a first order gives them the Customer role.
• Placing an order stores it as Awaiting payment, reserves stock, and emails Order confirmed to the customer and New order to the store.
• Failed payments keep the cart. If a Mollie payment fails, is cancelled, or expires, the customer returns to checkout with their items, a message explaining why, and a different method preselected. Retrying updates the same order instead of creating a new one.

Cart and checkout routes are rate limited per IP: adding or updating a cart line allows 30 requests a minute, and checkout and the catalog allow 60.

Inventory#

Commerce → Inventory shows available, reserved, and committed stock for each product and holds the stock policy.

Placing an order reserves tracked stock for the hold time: available goes down and reserved goes up. When the payment is captured, the quantity moves to committed. If the customer does not pay in time, it returns to available. A hold time of 0 commits stock only when the payment is captured. Opening Commerce → Inventory also commits stock for already-captured payments and releases expired holds.

Orders#

Commerce → Orders lists each order with the customer, items, payment, shipping, and total, with status tabs and counts. Opening an order shows its addresses, lines, tax, payments, refunds, fulfillments, downloads, stock holds, timeline, and emails.

The Status and notes box on an order changes its status or adds a private note. Every change goes on the timeline with who made it. Moving to Shipped, Delivered, or Cancelled can email the customer with the matching template. Changing a status needs the Update orders capability.

Customers#

Activating Shop adds a Customer role with no admin access. It appears in New User Default Role, user invites, and the user editor, and disappears again when Shop is deactivated. A user can hold it as their main role or as an additional role (see Users and roles).

• Add (Commerce → Customers → Add customer): sign-in email, name, phone, company, tax ID, invoice address, and shipping address. A new email creates a user with the Customer role. An email that already signs in is linked and given the Customer role; their password and main role stay the same.
• Edit: open a customer to change their details. The sign-in address stays on the user account.
• Import (Commerce → Customers → Import): CSV, JSON, or XML, including addresses. New emails create users; matching emails update the shop record and leave the sign-in alone. A 20-row sample ships as samples/customers-20.csv.
• Anyone given the Customer role from Admin → Users, an invite, or sign-up also appears in Commerce → Customers.

Payments#

Commerce → Payments lists every method, each on its own page. Open one, switch it on, enter the sandbox and/or live credentials, and save. Secrets are stored in encrypted plugin secrets and never sent back to the browser; the page only says whether one is set.

Mollie

On the Mollie page, choose Mollie checkout (one choice that opens Mollie's payment page) or the methods active on your Mollie profile (each its own choice that sends the customer straight to that method). Checkout offers one or the other, not both. Show payment method logos at checkout turns the icons on or off. Each Mollie payment includes the order lines with tax, billing and shipping addresses, the visitor's language, a cancel link, and the Justflows user, customer, and order ids in its metadata. The order stays Awaiting payment until Mollie reports it paid. Apple Pay is offered only in browsers that support it.

When a Mollie payment fails, is cancelled, or expires, the customer gets one Payment failed email with a {{payment_url}} link. It opens a Finish your payment page for the same order, where they can pay another way. Paid, cancelled, or refunded orders cannot be paid again from that link.

Capture, cancel, and refund

The Payments list shows every payment attempt. From an attempt you can capture an authorization (fully or partly), cancel an open authorization, or refund a captured amount (fully or partly). For card providers Shop sends the action to the provider; for manual methods (bank transfer, cash on delivery, check) it is only recorded.

Payment webhooks

Providers report payments, refunds, and disputes to a per-method URL. The token is random and created the first time you save the method. Treat the whole URL as a secret.

https://<your-site>/ext/justflows.shop/payments/hooks/<method>/<token>

Subscribe at least to payment success and failure, refunds, and disputes: Stripe payment_intent.*, charge.refunded, charge.dispute.*; Adyen AUTHORISATION, CAPTURE, REFUND, CHARGEBACK, NOTIFICATION_OF_CHARGEBACK; Square payment.*, refund.*, dispute.*; PayPal PAYMENT.CAPTURE.*, CUSTOMER.DISPUTE.*.

• One URL serves both modes. Shop checks each call with the credentials of the mode the store is in, so register the URL in the provider's test environment while sandbox is on, and in the live environment before you switch it off.
• Repeat deliveries of the same event are stored once. Disputes and chargebacks are added to the disputes list.
• Shop answers 200 when accepted, 400 when the signature or provider check fails, and 404 for an unknown method or wrong token. A wrong secret shows up as repeated failed deliveries in the provider's dashboard.
• Webhook routes skip the session CSRF token, keep the raw request body for signature checks, and are limited to 60 requests a minute per IP.

stripe listen --forward-to https://<tunnel>/ext/justflows.shop/payments/hooks/stripe/<token>

Shipping#

1. 1

   Origin

   The address you ship from.

2. 2

   Zones

   Match by country, postcode, or the rest of the world. When several zones match, the most specific wins (postcode beats country, country beats rest of the world); ties go to the zone's priority.

3. 3

   Methods

   Per zone: flat rate, free shipping, local pickup, or a carrier service (DHL Express / Parcel / eCommerce, DPD, PostNL).

4. 4

   Carriers

   Enter the API key (and secret where needed), then Test connection. DHL Express returns live rates, PostNL returns delivery options, and DPD signs in and lists pickup points. In sandbox mode the carriers' test hosts are used, and PostNL also creates and reads back a confirmed shipment on its shipping sandbox.

PostNL and DPD do not return contract prices, so for those two the rate you set on the zone method is what the customer pays. Carrier keys are stored in plugin secrets and never sent back to the browser.

Tax#

• Commerce → Tax: turn tax on, choose whether prices are entered including or excluding tax, and how they are shown in the catalog and at checkout. Shop warns when the combination would confuse customers.
• Calculate tax from the shipping, billing, or store address.
• Add tax classes (for example Standard, Reduced, Zero) and rates per country, optionally narrowed to a state, postcode, or city. Rates can be compound and have a priority.
• Shipping tax follows the cart items, a fixed class, or none. Round per line or on the subtotal, show one tax total or itemize it, and add a price suffix such as "incl. VAT". {price_including_tax} and {price_excluding_tax} insert those amounts in the suffix.
• Product pages, {{price}}, and related products use the catalog display. Before a customer address is known, the rate comes from the store address. When the catalog shows prices excluding tax, the product page shows the net price large and the including-tax price small beside it.

Discounts#

A discount is a code (generated or your own) or automatic. Limit it by minimum or maximum spend, total uses, uses per customer, products, categories, brands, customer emails or email domains, countries, first order only, and a start and end date. Under settings, choose how discounts combine (priority, combine, or exclusive) and whether they apply before or after tax.

Emails#

Commerce → Emails has an editable template per message and language (English, Dutch, German, French, and Spanish ship built in). Switch a message on or off and edit its subject and body. Emails go out through the site's outgoing mail, and each sent message is listed in the log on this page.

{{store_name}} {{customer_name}} {{order_number}} {{order_total}} {{order_url}}
{{payment_url}} {{tracking_number}} {{tracking_url}} {{refund_amount}} {{reason}}
{{product_name}} {{sku}} {{stock}} {{threshold}}

Staff access#

Shop registers user capabilities in groups. Custom roles and per-user grants can hand out any of them (see Users and roles).

Administrators have every capability. Deleting products, adjusting stock, capturing and refunding payments, and managing customers, discounts, tax, and shipping stay with administrators unless you grant them.

Static exports and diagnostics#

• Static export: Shop lists its cart, checkout, order confirmation, customer account, and order tracking pages, in every active language, through the staticExport.exclude filter. A static export skips them and the generated web-server config sends them to the live app. Catalog and product pages still export.
• Diagnostics: Admin → System → Diagnostics shows whether Shop setup is complete and whether each enabled payment gateway has credentials for the current mode (names only, never values). A gateway the provider rejects shows on the overview. Errors Shop logs appear under Recent errors as plugin:justflows.shop.
• Theme and URLs: while active, Shop adds customizer layout widths and default permalink bases for Product (/product) and Shop (/shop).

Extend Shop from another plugin#

Another plugin can add payment gateways and shipping carriers with two filters. Register them in activate(); they disappear when that plugin is deactivated.

ctx.hooks.filter("justflows.shop.payments.gateways", (gateways) => [
  ...gateways,
  {
    id: "acme-pay",
    name: "Acme Pay",
    manual: false,
    managed: false,
    capabilities: ["intent", "capture", "refund", "webhooks", "sandbox"],
    fields: [
      { id: "publicKey", label: "Public key", secret: false },
      { id: "secretKey", label: "Secret key", secret: true },
    ],
  },
]);

ctx.hooks.filter("justflows.shop.shipping.carriers", (carriers) => [
  ...carriers,
  {
    id: "acme-post",
    name: "Acme Post",
    origins: ["NL", "BE"],
    services: [{ id: "standard", label: "Acme Standard" }],
    capabilities: ["rates", "tracking"],
  },
]);

Products are ordinary content, so core webhooks already notify other systems when a product is created, updated, published, unpublished, or deleted. Act only on events where data.type is product. Shop does not emit its own order events yet.

HTTP routes#

All routes are under /ext/justflows.shop/. Each checks the session and a Shop capability, except the public catalog and the payment webhooks.

Uninstalling#

By default, removing Shop drops its shop_* tables (orders, customers, payments, and the rest) and deletes the Shop and Product content. To keep them, turn off Delete shop data when this plugin is removed and Delete shop pages and posts when this plugin is removed in Shop's settings before you remove the plugin. Deactivating alone deletes nothing.

Known limits in the beta#

• Refunds, Reports, and Checkout in the Commerce menu still open a placeholder page. Refunds are recorded from a payment attempt on the Payments page.
• Low stock and Out of stock emails can be edited but are not sent yet.
• Webhooks from Stripe, PayPal, Adyen, and Square are verified and recorded, but do not change an order's status on their own yet. Mollie payments do update the order.
• Shop does not yet send its own outbound events, such as "order paid".
• The admin screens are translated into English, Dutch, German, French, and Spanish only.