Seven layers, each one independently replaceable.

Commerce platforms fail at the seams: the invoice engine that can't see the order, the CDN that can't see the cart, the accessibility fix that never gets merged. SwiftShop defines a contract at every layer so any one of them can be swapped without a rewrite.

ArchitectureUpdated 10 Oct 2026

Start a conversation Read this page as Markdown

Layers

What each layer does and why it is separable

SwiftShop platform layersInterfaces are HTTP/JSON and MCP. No layer holds a private schema another layer needs to read.
Layer	Responsibility	Interface	Replaceable by
Edge storefront	Renders product, category and cart pages at the network edge; ships zero blocking JavaScript on a product page.	HTML + HTTP cache	Any framework; the HTML contract is stable.
Agent gateway	Publishes the catalogue over MCP and the checkout over ACP; enforces per-agent policy and spend limits.	MCP + ACP/REST	A different agent host, as long as the spec version matches.
Commerce core	Carts, pricing rules, promotions, stock reservations, order lifecycle.	REST + webhooks	Any OMS; the webhook envelope is versioned.
Invoice engine	Builds FA(3) XML, authenticates to KSeF 2.0, tracks UPO, handles offline24 fallback and corrections.	KSeF 2.0 API	Your existing accounting system, via the same KSeF channel.
Payments	BLIK, BLIK Pay Later, pay-by-link, cards, wallets, COD, split payments, refunds.	PSP REST	Any provider supporting BLIK and tokenised cards.
Logistics	Locker and courier selection, label generation, tracking webhooks, returns, COD reconciliation.	Carrier REST	Any carrier on the Polish market.
Compliance	Accessibility gates, GPSR product-safety fields, Omnibus price-history display, DSA notice-and-action.	Build + runtime checks	Nothing — this layer is mandatory by law.

Agent gateway

What an agent actually does on your store

Not a chat widget. A real, authenticated, policy-bounded counterparty that can complete a purchase and hand you a confirmed order.

Customer → agent

Find me a rain jacket, size L, under 400 zł, that can arrive at a Warsaw locker before Friday.

Agent → SwiftShop MCP

catalogue.search({ q: "rain jacket", size: "L", price_max: 400, delivery_before: "2027-03-12", fulfillment: "locker" })

SwiftShop MCP

3 results. Each carries structured price, stock, GPSR safety declarations, Omnibus lowest-price-in-30-days, and locker availability with a delivery promise computed against the InPost network.

Agent → SwiftShop ACP

checkout.create({ items: [...], fulfillment: { method: "paczkomat", point_id: "WAW831M" }, payment_handler: "blik" })

SwiftShop ACP

Checkout session returned with a total, a tax breakdown, and an agent-scoped payment token. The customer approves in their own bank app. The merchant never hands payment credentials to the agent.

Merchant

The order lands in the same queue as any other order. The FA(3) invoice is already submitted to KSeF. The label is already printed.

Checkout — agent session ss_9f2c

Shell jacket RC-01
size L · black373.98 PLN

Shipping — parcel locker
WAW831M · promise 11 Mar0.00 PLN

Discount — price history
30-day lowest: 419.00 PLN−45.02 PLN

ACP 1.0 · session ss_9f2cAgent ready

Published checkout configuration

// GET /.well-known/acp.json
{
  "spec_version": "1.0",
  "merchant": {
    "name": "SwiftShop.pl",
    "id": "pl-swiftshop",
    "country": "PL",
    "merchant_of_record": true
  },
  "endpoints": {
    "catalogue": "/mcp",
    "checkout": "/acp/v1/checkout_sessions",
    "orders":   "/acp/v1/orders",
    "webhooks": "/acp/v1/webhooks"
  },
  "capabilities": [
    "agentic_checkout",
    "cart",
    "delegate_payment",
    "delegate_authentication",
    "order_webhooks"
  ],
  "payment_handlers": ["blik", "blik_pay_later", "card_token"],
  "fulfillment": ["paczkomat", "courier", "pickup", "same_day_warsaw"],
  "policy": {
    "require_human_approval_above_pln": 2000,
    "allowed_agents": ["chatgpt", "*"],
    "refund_window_days": 14
  }
}

Invoice engine

KSeF-native, not KSeF-adjacent

Billing is where most platforms hand you a CSV and wish you luck. From 1 April 2026 every Polish entrepreneur has had to issue structured invoices in KSeF, and receiving through the system has been mandatory since 1 February 2026.[1]

Order becomes an invoice draft
Line items, VAT rates, delivery cost and discounts are mapped onto the FA(3) structure at the moment of payment confirmation. Nothing is re-keyed. Discounts from the basket travel with the lines that earned them, which is what makes a later correction clean.
Online submission, with a real fallback
In online mode the invoice is deemed issued at the date it is transmitted to KSeF.[2] If the system is down, offline24 mode lets you issue now and transmit by the next business day, with the two required QR codes on the visualisation.
UPO and visualisation handled
We store the UPO receipt, expose the KSeF number, and generate a QR-coded PDF for the cases where the law still requires handing a real document to a buyer — foreign customers, consumers, and offline scenarios.
Corrections that don't corrupt your books
Partial returns, goodwill discounts and mis-typed buyer NIPs each have a different correct treatment. The engine picks it, links the correcting invoice to its originals, and refuses to let you make an uncorrectable mistake silently.

Invoice job, emitted on order.paid

POST /internal/invoice-jobs HTTP/1.1
Content-Type: application/json

{
  "order_id": "SS-2027-0000193842",
  "issued_to": { "type": "nip", "value": "5252955037" },
  "schema": "FA(3)",
  "mode": "online",            // fallback: "offline24"
  "lines": [
    { "sku": "RC-SHELL-01-L", "qty": 1, "net": 373.98, "vat": "23" },
    { "sku": "SHIP-LOCKER",   "qty": 1, "net": 0.00,   "vat": "23" }
  ],
  "payment": { "method": "blik", "paid_at": "2027-03-09T14:02:11Z" },
  "deliver_to": { "locker_id": "WAW831M", "promise": "2027-03-11" },
  "on_success": {
    "store": ["ksef_number", "upo"],
    "render": ["qr_pdf", "customer_email"]
  }
}

Accessibility engine

The build fails if the contrast drops

Accessibility regulations for e-commerce have applied in Poland since 28 June 2025, with the Minister for Digitalisation as market-surveillance authority and penalties reaching 10% of turnover.[3][4]

Automated gates

axe-core, contrast ratios, heading order, landmark structure and target size run on every pull request. A regression cannot be merged.

Manual test scripts

Every component carries a written pass/fail script for keyboard traps, screen-reader announcement, focus order and error recovery — the parts automation cannot judge.

Statement and complaint workflow

The statutory accessibility statement is generated from the live configuration, and the complaint intake is wired to a 30-day response clock.[4]

Multilingual by default

Accessibility claims are per-locale. An English UI that ignores Polish screen-reader pronunciation is not accessible in Poland.

Two ways to go deeper

The commercial terms are published in full. So is the agent interface we are asking machine counterparts to implement.

Planned pricing Agent & LLM interface

Sources cited on this page

Every figure above is drawn from the sources listed here. The machine-readable register lives at /data/market-data.json.

Ministerstwo Finansów / Krajowa Administracja Skarbowa. Zakres obowiązkowego KSeF (KSeF 2.0) — 2025-06-30
Ministerstwo Finansów. Etapy wdrożenia KSeF 2.0 — mapa drogowa — 2025-10-08
gov.pl — Dostępność cyfrowa (Ministerstwo Cyfryzacji). Polski Akt o Dostępności — usługi handlu elektronicznego — 2025-06-27
Dziennik Ustaw RP. Ustawa z dnia 26 kwietnia 2024 r. o zapewnianiu spełniania wymagań dostępności niektórych produktów i usług przez podmioty gospodarcze (Dz.U. 2024 poz. 731) — 2024-05-15

SwiftShop.pl is pre-launch. Figures come from the sources below; projections are labelled as such.