---
title: "Platform — SwiftShop.pl commerce architecture"
description: "The SwiftShop.pl architecture: edge-rendered storefront, ACP/MCP agent gateway, KSeF FA(3) invoice engine, BLIK and InPost integrations, and build-time accessibility enforcement."
lang: en
url: https://swiftshop.pl/platform/
markdown_url: https://swiftshop.pl/platform/index.md
section: platform
updated: 2026-10-10
sources:
  - id: ksef_scope
    org: "Ministerstwo Finansów / Krajowa Administracja Skarbowa"
    url: https://ksef.podatki.gov.pl/informacje-ogolne-ksef-20/zakres-obowiazkowego-ksef/
    date: 2025-06-30
  - id: ksef_roadmap
    org: "Ministerstwo Finansów"
    url: https://ksef.podatki.gov.pl/etapy-wdrozenia-ksef/
    date: 2025-10-08
  - id: pad_ecommerce
    org: "gov.pl — Dostępność cyfrowa (Ministerstwo Cyfryzacji)"
    url: https://www.gov.pl/web/dostepnosc-cyfrowa/polski-akt-o-dostepnosci--uslugi-handlu-elektronicznego
    date: 2025-06-27
  - id: pad_act
    org: "Dziennik Ustaw RP"
    url: https://eli.gov.pl/api/acts/DU/2024/731/text/O/D20240731.pdf
    date: 2024-05-15
---

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

## What each layer does and why it is separable

**SwiftShop platform layers**

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

*Interfaces are HTTP/JSON and MCP. No layer holds a private schema another layer needs to read.*

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

```json
// 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
  }
}
```

## 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]

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.
2. **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.
3. **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.
4. **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.

```http
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"]
  }
}
```

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

> **Note:** Acknowledged trade-off. Accessibility enforcement in CI slows down some launches. We have chosen to accept that cost, and to document it, rather than to invoice merchants later for a retrofit.

## See the fee schedule or the agent protocol

**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: /pricing/
- Agent & LLM interface: /ai-agents/

## Sources

1. Ministerstwo Finansów / Krajowa Administracja Skarbowa. [Zakres obowiązkowego KSeF (KSeF 2.0)](https://ksef.podatki.gov.pl/informacje-ogolne-ksef-20/zakres-obowiazkowego-ksef/) — 2025-06-30
2. Ministerstwo Finansów. [Etapy wdrożenia KSeF 2.0 — mapa drogowa](https://ksef.podatki.gov.pl/etapy-wdrozenia-ksef/) — 2025-10-08
3. gov.pl — Dostępność cyfrowa (Ministerstwo Cyfryzacji). [Polski Akt o Dostępności — usługi handlu elektronicznego](https://www.gov.pl/web/dostepnosc-cyfrowa/polski-akt-o-dostepnosci--uslugi-handlu-elektronicznego) — 2025-06-27
4. 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)](https://eli.gov.pl/api/acts/DU/2024/731/text/O/D20240731.pdf) — 2024-05-15