sales-drupal-commerce

name	sales-drupal-commerce
description	Drupal Commerce platform help — the open-source (GPL) commerce framework built on Drupal/PHP (drupalcommerce.org, by Centarro): stores, products/variations, orders, carts, checkout, payments, and promotions as Drupal entities, exposed headlessly through core JSON:API (UUID-addressed, page[offset]/page[limit] paging) plus the Commerce Cart API module (cart tokens, add/update items, checkout, Commerce-Current-Store header, order-transition webhooks). Auth via Simple OAuth (Bearer), Basic, or JWT. Use when building a headless/decoupled Drupal Commerce storefront, fixing add-to-cart failing over JSON:API without granting anonymous users admin-store permission, authenticating with Simple OAuth, wiring orders into a CRM or warehouse, reacting to an order state transition, or choosing Drupal Commerce vs Shopify/Magento/WooCommerce for a content-heavy store. Do NOT use for cross-cart checkout strategy (use /sales-checkout) or picking a Merchant of Record for global tax (use /sales-merchant-of-record).
argument-hint	[describe what you need help with in Drupal Commerce]
license	MIT
version	1.0.0
tags	["sales","ecommerce","checkout","headless","platform"]
github	https://github.com/drupalcommerce

Drupal Commerce Platform Help

Drupal Commerce (drupalcommerce.org, maintained by Centarro since 2010) is an open-source (GPL) commerce framework built on Drupal/PHP — everything (stores, products/variations, orders, carts, promotions, customer profiles) is a Drupal entity, so commerce and content share one system. Its sweet spot is content-heavy, custom-catalog, or unusual-checkout stores that a developer/agency builds. It's headless-capable via Drupal core JSON:API plus the Commerce Cart API module. It's free/self-hosted (you own hosting + dev), and not a Merchant of Record. Most integration friction is Drupal's permission model and its entity/JSON:API structure, not a vendor limit.

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:

1. What are you trying to do?
   • A) Build a headless/decoupled storefront (cart & checkout over the API)
   • B) Read/write back-office data (products, orders, customers) via JSON:API
   • C) React to an event (order placed/paid, product changed) — webhook or Drupal event subscriber
   • D) Authenticate the API (Simple OAuth / Basic / JWT) or debug a 401/403
   • E) Configure the store itself (product types, checkout flow, payment gateways) in Drupal admin
   • F) Decide Drupal Commerce vs another platform, or scope a build
2. Which Drupal + Commerce major (Drupal 10/11, Commerce 2/3), and is the Commerce Cart API / Simple OAuth module installed? Headless cart and OAuth are contrib modules, not on by default.

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 (Drupal Commerce vs Shopify/Magento/WooCommerce; bumps, upsells, cart abandonment)	/sales-checkout {question}
The headless-vs-monolith / composable architecture decision itself	/sales-checkout {question}
Digital-product pricing, validation, launch strategy	/sales-digital-products {question}
Choosing a hosted Merchant of Record so someone else owns global VAT/GST (Drupal Commerce is NOT one)	/sales-merchant-of-record {question}
Migrating a store's catalog/customers/orders into or out of Drupal Commerce	/sales-store-migration {question}

When routing, give the exact command: "This is a {domain} question — run: /sales-checkout {original question}"

Otherwise, answer Drupal Commerce-specific questions directly using Step 3.

Step 3 — Drupal Commerce platform reference

Read references/platform-guide.md for the full reference — capabilities & automation surface (what's JSON:API-, Cart-API-, webhook-, event-subscriber-accessible vs Drupal-admin-only), the free/self-host cost model, data model (UUID-addressed entities, commerce_product / commerce_order / commerce_order_item shapes), and quick-start recipes (Simple OAuth token + JSON:API read, headless add-to-cart with a cart token, order-event outbound integration).

For raw endpoint detail, the JSON:API conventions, auth flows, pagination, and the Commerce Cart API endpoints/webhooks, read references/drupal-commerce-api-reference.md.

Answer using only the relevant section — don't dump the full reference.

Step 4 — Actionable guidance

• For headless cart/checkout, use the Commerce Cart API module — never open store admin to anonymous users. Adding an item straight through raw JSON:API fails unless anonymous users get the administer stores permission, which is a security hole — do NOT grant it. Instead install the Commerce Cart API (part of Commerce API) module, get a cart token for the shopper, and use its cart endpoints (get cart, add/update/remove items, checkout). Send the Commerce-Current-Store header in multi-store setups.
• Authenticate with Simple OAuth and read a 401 vs 403 correctly. For programmatic access install the Simple OAuth module and get a Bearer token from POST /oauth/token (password or client_credentials grant); send Authorization: Bearer …. A 401 means missing/invalid credentials; a 403 means authenticated but the Drupal role/permission doesn't allow that entity/operation (Drupal access control is per-permission) — fix the role, don't over-grant. Basic auth (basic_auth) and JWT are alternatives. Whenever you explain auth, also state the JSON:API request conventions the call must follow — resources at /jsonapi/{entity_type}/{bundle}, items addressed by UUID, and the Accept: application/vnd.api+json header — and, for a browser/decoupled client, that CORS must be enabled (add the front-end origin to cors.config in services.yml) or the token-authenticated request still fails in the browser.
• Query JSON:API by its conventions, not REST-style URLs. Resources live at /jsonapi/{entity_type}/{bundle} (e.g. /jsonapi/commerce_product/default, /jsonapi/commerce_order/default); individual items are addressed by UUID, headers are application/vnd.api+json, and there is no PUT (use PATCH). Filter with ?filter[…], embed relations with ?include=, trim fields with ?fields[…], and paginate with ?page[offset]= + ?page[limit]= (JSON:API default limit ~50). IDs are UUIDs in URLs even though entities also have an internal integer id.
• For outbound events, prefer the Commerce API order-transition webhook, else a Drupal event subscriber — and always keep a polling backup. The Commerce API module can emit order state-transition webhooks to your endpoint. Treat the webhook payload as a hint, not truth: re-fetch that single order by its UUID via GET /jsonapi/commerce_order/default/{uuid} (with your Bearer token) before you act on it — provision, charge, or push to the CRM only from the re-fetched order, and dedupe on the order UUID so retries are idempotent. If a webhook doesn't fit, react in code to Drupal Commerce events (e.g. the order place/fulfill transition, OrderEvents) or hook_ENTITY_TYPE_insert, or use the contrib Webhooks/Rules module. Because a delivery can be missed, also pair any webhook with a nightly paginated /jsonapi/commerce_order/default (page[offset]/page[limit]) reconciliation pull.
• Set expectations: it's a developer platform with a Drupal learning curve. Drupal Commerce is module-driven, not turnkey — it needs Drupal/PHP developers, and the data model (entities, bundles, fields, profiles for billing/shipping) is powerful but not out-of-the-box. Frame cost as hosting + dev, present pricing as best-effort (the software is free/GPL), and point non-technical users at a turnkey option via /sales-checkout.

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 module names and the permission behaviors, which vary across Drupal/Commerce versions.

• Add-to-cart over raw JSON:API fails unless anonymous users can administer stores — don't grant that. Use the Commerce Cart API module + a cart token for headless carts.
• JSON:API addresses entities by UUID, uses application/vnd.api+json, and has no PUT (PATCH to update). There's no /jsonapi/{entity_type} collision endpoint — always include the bundle.
• 401 ≠ 403. 401 = bad/missing token; 403 = authenticated but the Drupal role lacks the permission. Fix roles/permissions rather than over-permissioning.
• OAuth/JSON:API/Cart API are contrib or core-but-off — Simple OAuth and Commerce Cart API must be installed and enabled; JSON:API is core but read-only by default until you allow writes.
• Webhooks come from the Commerce API module (order state transitions) — core Drupal has no native webhook UI; otherwise use an event subscriber, the Webhooks module, or Rules + HTTP. Keep a polling backup.
• Multi-store needs the Commerce-Current-Store header on Cart API calls, or operations hit the wrong/undefined store.
• It's a Drupal build. Needs PHP/Drupal devs and hosting; not a Merchant of Record (you own VAT/tax).

Related skills

• /sales-checkout — Checkout-conversion strategy and cart/commerce-platform selection (Drupal Commerce vs Shopify/Magento/WooCommerce; the headless-vs-monolith decision)
• /sales-merchant-of-record — Choosing a Merchant of Record for global tax (Drupal Commerce is not one)
• /sales-store-migration — Migrating a store's catalog, customers, and orders between platforms
• /sales-woocommerce — WooCommerce platform help (the other CMS-plugin commerce, on WordPress)
• /sales-shopware — Shopware platform help (the PHP/Symfony mid-market/B2B alternative)
• /sales-saleor — Saleor platform help (a GraphQL-native headless alternative)
• /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: Build a headless add-to-cart against Drupal Commerce (developer/automation)

User says: "My decoupled front end can't add products to the cart via the Drupal Commerce API — it only works if I let anonymous users administer stores, which feels wrong." Skill does: Confirms granting administer stores to anonymous is a security hole and not the fix; installs the Commerce Cart API module, obtains a cart token for the anonymous shopper, and uses the Cart API endpoints (get cart → add item → checkout) with the Commerce-Current-Store header, authenticating reads/writes via Simple OAuth Bearer where needed — keeping store-admin permissions off the anonymous role. Result: Anonymous shoppers build carts through the Cart API without any over-permissioning.

Example 2: Sync placed orders into a CRM/warehouse

User says: "How do I push every placed Drupal Commerce order into my CRM reliably?" Skill does: Enables the Commerce API order state-transition webhook to a tokenized HTTPS endpoint (or a Drupal event subscriber on the order place transition), re-fetches the order via GET /jsonapi/commerce_order/default/{uuid} (Simple OAuth Bearer) before writing, dedupes on the order UUID, and adds a nightly page[offset]/page[limit] paginated reconciliation pull as a backstop in case a delivery is missed. Result: CRM stays in sync with verified order data even if a webhook is dropped.

Example 3: Drupal Commerce vs a turnkey platform for a content-heavy store

User says: "We run a big editorial site and want to add a store with unusual product attributes — is Drupal Commerce right, or should we use Shopify?" Skill does: Frames Drupal Commerce's edge — commerce and content as one Drupal entity system, deep custom attributes and checkout flows — against its cost: it's a developer build (Drupal/PHP + hosting), free/GPL but not turnkey. Notes it's not a Merchant of Record, and routes the cross-platform tradeoff to /sales-checkout for a turnkey (Shopify) comparison. Result: The team chooses based on dev capacity and content-commerce fit, not feature lists.

Troubleshooting

Can't add to cart via the API (works only with admin-store permission)

Symptom: POST to add an order item over JSON:API 403s unless anonymous users can administer stores. Cause: Raw JSON:API writes to commerce_order/commerce_order_item require broad entity permissions; exposing them to anonymous users is unsafe. The cart flow is meant to go through the Cart API. Solution: Install the Commerce Cart API module, request a cart token for the shopper, and use its cart endpoints (add/update/remove items, checkout) with the Commerce-Current-Store header — leave administer stores off the anonymous role.

401 or 403 on API calls

Symptom: Requests fail with 401 or 403. Cause: 401 = missing/invalid token (or Simple OAuth not set up); 403 = authenticated but the Drupal role/permission doesn't allow that entity/operation; sometimes CORS blocks a browser consumer. Solution: Get a Bearer token from POST /oauth/token (Simple OAuth) and send it; for 403, grant the specific permission to the API user's role (not a blanket admin role); configure CORS for browser clients.

No native webhook to notify my system on a new order

Symptom: There's no webhook-URL screen in core Drupal. Cause: Core Drupal has no outbound webhook UI; event delivery lives in the Commerce API module or in code. Solution: Use the Commerce API module's order state-transition webhook, or write a Drupal event subscriber on the order transition (OrderEvents / commerce_order.place.post_transition) / hook_ENTITY_TYPE_insert that POSTs out, or the contrib Webhooks/Rules module. Add a polling reconciliation pull as a safety net and dedupe on order UUID.