Shopware platform help — the open-source PHP/Symfony commerce platform (shopware.com, Shopware 6): products, orders, customers, and two APIs — the Admin API (/api/*, OAuth 2.0 client-credentials via an Integration, 300 req/min) and the headless Store API (/store-api/*, sw-access-key), plus app webhooks (shopware-shop-signature HMAC-SHA256) and Flow Builder automation. Use when generating an Admin API OAuth token or debugging a 401 from extension-generated keys, searching entities via POST /api/search/{entity} with Criteria, wiring orders or customers into a CRM or warehouse, registering an app webhook for checkout.order.placed, building a headless storefront on the Store API, hitting the 300-req/min rate limit or random admin logouts, or choosing between the free Community Edition and the paid Rise/Evolve/Beyond plans under the GMV fair-usage policy. Do NOT use for checkout-conversion strategy across carts (use /sales-checkout) or picking a Merchant of Record for global tax (use /sales-merchant-of-record).
Standardmäßig ist der Prompt ausgewählt, der zuerst die Quelle prüft. Sie können zu einem direkten Befehl wechseln oder eine lokale Kopie herunterladen.
Quelldateien prüfen
Lesen Sie SKILL.md und alle von SkillsMP angezeigten Begleitdateien, bevor Sie sich für eine Installation entscheiden.
Mit Codex oder Claude installieren Kopieren Sie diesen Prompt, fügen Sie ihn in Codex, Claude oder einen anderen Assistant ein und lassen Sie die Skill-Seite prüfen und installieren.
Ein direkter Befehl überspringt den Prüf-Prompt. Prüfen Sie die Quelle, bevor Sie ihn ausführen.
Shopware platform help — the open-source PHP/Symfony commerce platform (shopware.com, Shopware 6): products, orders, customers, and two APIs — the Admin API (/api/*, OAuth 2.0 client-credentials via an Integration, 300 req/min) and the headless Store API (/store-api/*, sw-access-key), plus app webhooks (shopware-shop-signature HMAC-SHA256) and Flow Builder automation. Use when generating an Admin API OAuth token or debugging a 401 from extension-generated keys, searching entities via POST /api/search/{entity} with Criteria, wiring orders or customers into a CRM or warehouse, registering an app webhook for checkout.order.placed, building a headless storefront on the Store API, hitting the 300-req/min rate limit or random admin logouts, or choosing between the free Community Edition and the paid Rise/Evolve/Beyond plans under the GMV fair-usage policy. Do NOT use for checkout-conversion strategy across carts (use /sales-checkout) or picking a Merchant of Record for global tax (use /sales-merchant-of-record).
Shopware (shopware.com) is an open-source PHP/Symfony commerce platform (Shopware 6) aimed at
mid-market and B2B merchants, strong in Europe, and built for dev/agency-owned stores rather
than click-together SaaS. The Community Edition is free (MIT) and self-hosted; paid Rise /
Evolve / Beyond tiers and Shopware Cloud add automation, B2B, and support. It exposes two
distinct HTTP APIs — the Admin API (/api/*, back-office) and the Store API
(/store-api/*, headless storefront) — plus a webhook-capable App system and Flow Builder
automation. It is heavier than EverShop/Medusa: expect to run PHP/Symfony infra.
Step 1 — Gather context
If references/learnings.md exists, read it first for accumulated platform knowledge.
Ask only what you can't infer from the user's prompt:
What are you trying to do?
A) Read/write back-office data (products, orders, customers) via the Admin API
B) Build a headless / custom storefront (Store API cart & checkout)
C) React to events (order placed, product changed) via an app webhook or Flow Builder
D) Bulk-import/sync a catalog (Sync API, search Criteria, pagination)
E) Configure the store itself (sales channels, products, plugins) in the Administration
F) Choose an edition (Community vs Rise/Evolve/Beyond, self-host vs Cloud) or understand the GMV fair-usage policy
Self-hosted or Shopware Cloud, and which version (6.5 / 6.6 / 6.7)? Field shapes and the admin
stack differ across majors; Cloud restricts plugin installs to the store and the App system.
Skip-ahead rule: if the user's prompt already has enough context, go straight to Step 2.
Step 2 — Route or answer directly
If the user's question is about…
Route to
Which cart/commerce platform to pick, or checkout-conversion strategy (Shopware vs Shopify/Magento/Medusa; bumps, upsells, cart abandonment)
/sales-checkout {question}
The headless-vs-monolith / composable architecture decision itself
Choosing a hosted Merchant of Record so someone else owns global VAT/GST (Shopware is NOT one)
/sales-merchant-of-record {question}
Migrating an existing store's catalog/customers/orders into or out of Shopware
/sales-store-migration {question}
When routing, give the exact command: "This is a {domain} question — run: /sales-checkout {original question}"
Otherwise, answer Shopware-specific questions directly using Step 3.
Step 3 — Shopware platform reference
Read references/platform-guide.md for the full reference — capabilities & automation surface
(what's Admin-API-, Store-API-, webhook-accessible vs Administration-only), editions/pricing and the
GMV fair-usage gate, data model (UUID-hex IDs, the search-Criteria query model, translatable
fields), and quick-start recipes (OAuth token + entity search, Sync API bulk upsert, app webhook
with signature verification).
For raw endpoint detail, the OAuth flows, Criteria/pagination, Sync API, and verbatim webhook
events/signature, read references/shopware-api-reference.md.
Answer using only the relevant section — don't dump the full reference.
Step 4 — Actionable guidance
Authenticate the Admin API with a manually-created Integration, and read a 401 as the wrong
credential source. Get the OAuth token via POST /api/oauth/token with
grant_type=client_credentials, client_id=Access Key ID, client_secret=Secret Access Key from
Settings → System → Integrations. If a 401/"token invalid" appears, the usual cause is using
keys returned by a plugin/extension install (which often can't mint tokens) or a stale token —
create a dedicated Integration instead, and refresh the Bearer token before it expires (expires_in
is ~3600s). For the Store API, authenticate with the sw-access-key sales-channel key, not OAuth.
Query with the search-Criteria model, not REST filters in the URL. Most reads are
POST /api/search/{entity} with a JSON Criteria body (filter, sort, limit, page,
associations, aggregations) — plain GET /api/{entity} exists but real queries go through
/search. Paginate with limit + page (not offset) and set total-count-mode when you need a
count. IDs are 32-char hex UUIDs, and translatable fields resolve by the request's language context.
Bulk-write through the Sync API, and respect 300 req/min. For imports/upserts/deletes use
POST /api/_action/sync (batched operations in one call) rather than one request per row. The
Admin API is capped at 300 requests/minute — on 429 back off and resume; keep syncs
incremental and batched. Store API limits vary by server config.
For outbound events, register an App-system webhook and verify the signature. Events fire from
the App system (manifest <webhooks> with name/url/event), e.g. checkout.order.placed,
state_enter.order_transaction.state.paid, product.written, order.written. Every delivery
carries a shopware-shop-signature header = HMAC-SHA256 of the raw request body keyed by
the app secret assigned at registration — recompute and compare (constant-time) before trusting it,
then re-fetch the entity via the Admin API. Add onlyLiveVersion: true so order drafts don't
fire, and keep a polling backup. Flow Builder can also POST to an HTTP endpoint as an action.
Warn about the GMV fair-usage gate and self-host reality. Present all pricing as best-effort:
Community Edition is free/MIT, but under the Fair Usage Policy (from March 2026) a store over
~€1M GMV must move to a paid plan (Rise/Evolve/Beyond) — flag this early for anyone scaling.
Self-hosting means running PHP/Symfony + MySQL/OpenSearch + a message queue; it needs developers
and real hosting/PCI budget. Verify current numbers at shopware.com/pricing.
If the admin keeps logging out, it's the known token-refresh race, not the user. Randomly
losing the Administration session (especially across multiple tabs) is a long-standing refresh-token
race condition — reduce to a single admin tab, clear the session, and check for the latest patch;
it's not a misconfiguration on their end.
If you discover a gotcha or tip not in references/learnings.md, append it there with today's date.
Gotchas
Best-effort from research (2026-07) — review these, especially edition pricing, the GMV fair-usage
threshold, and the auth behaviors, which change across versions.
Admin API auth = OAuth via an Integration, Store API = sw-access-key. Don't mix them; a 401 is
usually keys from a plugin-install response (can't mint tokens) — use a manual Integration.
The query model is POST /api/search/{entity} with a Criteria body — filters/sort/pagination
go in JSON, not URL query params. Pagination is limit+page, not offset.
300 requests/minute on the Admin API — batch with the Sync API (/api/_action/sync) and back off on 429.
Webhooks come from the App system, signed with shopware-shop-signature (HMAC-SHA256 of the raw
body). Use onlyLiveVersion to skip order drafts; verify before trusting.
GMV fair-usage gate — Community Edition is free, but from March 2026 a store over ~€1M GMV must
buy a paid plan. Flag for scaling merchants.
Random admin logouts = the refresh-token race condition (multi-tab), not a config error.
Self-hosting is heavy — PHP 8.2+/Symfony, MySQL/MariaDB, OpenSearch, message queue; needs devs.
It's not a Merchant of Record (you own VAT/tax).
IDs are 32-char hex UUIDs and many fields are translatable by language context — don't assume
integer IDs or a single locale.
Related skills
/sales-checkout — Checkout-conversion strategy and cart/commerce-platform selection (Shopware vs Shopify/BigCommerce/Magento/Medusa; the headless-vs-monolith decision)
/sales-merchant-of-record — Choosing a Merchant of Record for global tax (Shopware is not one)
/sales-store-migration — Migrating a store's catalog, customers, and orders between platforms
/sales-woocommerce — WooCommerce platform help (the self-hosted WordPress-plugin alternative)
/sales-prestashop — PrestaShop platform help (the other self-hosted PHP commerce platform)
/sales-medusa — Medusa platform help (the Node/TS headless alternative for lighter self-hosted stacks)
/sales-do — Not sure which skill to use? The router matches any sales objective to the right skill. Install: npx skills add sales-skills/sales --skill sales-do -a claude-code
Examples
Example 1: Sync new Shopware orders into a CRM/warehouse (developer/automation)
User says: "How do I push every placed Shopware order into my CRM automatically and reliably?"
Skill does: Registers an App-system webhook on checkout.order.placed (with
onlyLiveVersion: true so drafts don't fire) to a tokenized HTTPS endpoint, verifies each delivery
by recomputing HMAC-SHA256 of the raw body against the shopware-shop-signature header, then
re-fetches the order with POST /api/search/order (OAuth Bearer from an Integration) before writing —
deduping on the order id. Adds a batched Sync API / paginated /search reconciliation pull as a
backstop and notes the 300 req/min Admin-API cap.
Result: CRM stays in sync with verified data even if a delivery is missed, within the rate limit.
Example 2: Every Admin API call returns 401 "token invalid"
User says: "I got an access key and secret from a Shopware plugin but I can't generate an OAuth token — 401 every time."
Skill does: Explains that plugin/extension-returned keys often can't mint tokens; walks the
user to create a dedicated Integration under Settings → System → Integrations, then
POST /api/oauth/token with grant_type=client_credentials + that Integration's Access Key ID
/ Secret Access Key, and to send the resulting Bearer token (refreshing before expires_in).
Notes the Store API uses sw-access-key instead, not OAuth.
Result: Token generation works with a proper Integration; the 401 was the wrong key source.
Example 3: Community Edition vs a paid plan for a scaling store
User says: "We're on free Shopware Community Edition doing about €1.5M/year — do we have to pay now?"
Skill does: Flags the Fair Usage Policy (from March 2026) — CE is free only under ~€1M GMV,
so at €1.5M they fall into a paid tier (Rise/Evolve/Beyond), where the choice is driven by B2B/support
needs and GMV, not core features; notes CE is still self-hosted (they cover hosting/dev). Presents all
figures as best-effort to verify at shopware.com/pricing.
Result: The team plans for a paid plan they now legally need, chosen by needs rather than feature FOMO.
Troubleshooting
401 / "token invalid" on the Admin API
Symptom: POST /api/oauth/token or authenticated calls return 401.
Cause: Using Access Key/Secret returned by a plugin install (which frequently can't generate
tokens), an expired Bearer token, or hitting the Store API path with OAuth (or vice-versa).
Solution: Create a dedicated Integration (Settings → System → Integrations) and use its
Access Key ID as client_id and Secret Access Key as client_secret with
grant_type=client_credentials; refresh the Bearer before expires_in (~3600s). Use sw-access-key
for the Store API, OAuth only for /api/*.
Randomly logged out of the Administration
Symptom: The admin session drops unexpectedly, especially with multiple tabs open.
Cause: A long-standing refresh-token race condition — not a misconfiguration.
Solution: Work in a single admin tab, clear the session/cookies, and update to the latest patch
release; if scripting the Admin API, manage one token per client and refresh serially rather than racing.
Slow responses / 429 Too Many Requests
Symptom: Bulk reads/writes slow down or start returning 429.
Cause: The Admin API caps at 300 requests/minute; unbatched per-row writes and uncached
queries compound it.
Solution: Batch writes through the Sync API (POST /api/_action/sync), paginate reads with
Criteria limit+page, enable HTTP cache/Redis/OpenSearch, and back off on 429 before resuming.
