Step 1 — Gather context
If references/learnings.md exists, read it first for accumulated platform knowledge.
Figure out what the user actually needs before diving in:
- Goal — building/debugging an API integration, syncing orders/products to a CRM or warehouse, a checkout/conversion question, an install/ops problem, or a platform-selection decision?
- Surface — REST API (
/api/shop,/api/admin), GraphQL API (/api/graphql), the older headlessbagisto/graphql-apipackage (/graphql), the admin panel UI, or a marketplace/POS add-on? - Auth — Laravel Sanctum bearer token, the
X-STOREFRONT-KEYstorefront key, a guest cart token, or JWT (legacy headless package)? - Hosting — self-hosted (own infra: PHP/Laravel + MySQL/MariaDB + Redis) or Bagisto Cloud (managed)?
- Version — Bagisto 2.x line (current; v2.4.x as of mid-2026)? API packages need 2.3.0+.
Skip-ahead rule: if the prompt already says what they need, go straight to Step 2.
Step 2 — Route or answer directly
If the question is really a cross-platform strategy, hand off with the exact command:
| If the user wants… | Route to |
|---|---|
| Checkout conversion / order bumps / cart-abandonment tactics across carts | /sales-checkout {question} |
| Whether to use a Merchant of Record for global VAT/sales tax | /sales-merchant-of-record {question} |
| Digital-product pricing & launch strategy | /sales-digital-products {question} |
| Post-purchase email / abandoned-cart sequences | /sales-email-marketing {question} |
| Comparing Bagisto against another commerce backend | /sales-checkout {question} (platform selection) |
Otherwise it's a Bagisto-specific question — answer it here.
Step 3 — Bagisto platform reference
Read references/platform-guide.md for the full reference — modules and what's API vs event vs UI-only, pricing/plan posture, data model with JSON shapes, and quick-start recipes. For raw auth/endpoint/pagination detail, read references/bagisto-api-reference.md.
Answer using only the relevant section — don't dump the whole guide.
Step 4 — Actionable guidance
- Pick the right auth for the surface. The current unified API uses a public
X-STOREFRONT-KEY(pk_storefront_..., generated at install or viaphp artisan bagisto-api:generate-key) on every Shop call, plus a Laravel Sanctum bearer token (Authorization: Bearer 1|...) for customer/admin-scoped routes. Guests get a cart token (POST /api/shop/cart-tokens). The older standalonebagisto/graphql-api(Mobikul) package instead uses JWT + anx-app-secret-keyheader — don't mix the two. - Two API flavors, same engine. REST (
/api/shop/...,/api/admin/...) and GraphQL (/api/graphql, playground at/api/graphiql) both split into a public Shop API and a protected Admin API. Choose REST for simple CRUD/scripts, GraphQL when a headless storefront wants to request exactly the fields it needs. - There are no native outbound webhooks in core. Bagisto is a Laravel app — to notify a CRM/warehouse on an order, react to the Laravel event (e.g.
checkout.order.save.after) in a listener andfetch()out yourself, schedule a polling job against/api/admin/orders, or add a community webhook package. Don't expect a Shopify-style "webhooks" settings page. - Self-host is free; Cloud is for not running infra. The engine is MIT and free with no per-sale fee. Bagisto Cloud (Starter / Pro) sells managed, scalable hosting (uptime SLA, backups, support) so you don't run the LAMP/Redis stack yourself.
If you discover a gotcha or fix not in references/learnings.md, append it there with today's date.
Gotchas
Best-effort from research (2026-06) — re-verify plan gates, fees, auth headers, and API package versions against live docs.
- Broken images / mixed-content after setup or a move. The #1 post-install issue:
APP_URLin.envmust exactly match the real site URL (scheme + host). A mismatch breaks asset/image URLs; serving assets over HTTP on an HTTPS site triggers browser mixed-content blocking. FixAPP_URL, thenphp artisan optimize:clear. - Slow first loads / extreme slowness. Fresh installs can crawl until caches are built and a queue worker + Redis are configured. Run
php artisan optimize/ route+view+config caching, use Redis for cache & sessions, and run a real queue worker. Bundle-product price calculation is a known slow path on category pages — cache aggressively or limit bundles per listing. - Install fails at the last step / "Impossible to create the root directory." Almost always file-permission/ownership or PHP-extension gaps. Ensure
storage/andbootstrap/cache/are writable by the web user and required PHP extensions are present before re-running the installer. - Two API generations exist. The current docs (api-docs.bagisto.com) describe a unified REST+GraphQL with
X-STOREFRONT-KEY+ Sanctum; the olderbagisto/graphql-apipackage uses JWT +x-app-secret-keyand a/graphqlendpoint. Tutorials mix them — confirm which package is installed before quoting headers/endpoints. - API is a separate install. REST/GraphQL aren't always on by default —
composer require bagisto/rest-api(orbagisto/graphql-api) then run the package'sphp artisan ...:install. The GraphQL package needs middleware tweaks inbootstrap/app.php. - GraphQL schema must be cached in prod. Run
php artisan lighthouse:cachefor production andphp artisan lighthouse:clear-cacheafter schema changes, or queries get slow / stale.
Related skills
/sales-checkout— Checkout-conversion strategy across carts (order bumps, upsells, cart-abandonment recovery) and platform selection./sales-medusa— Another open-source, self-hostable headless commerce engine (Node.js/TypeScript, MIT) — compare if you're choosing a stack; Bagisto is Laravel/PHP./sales-saleor— Open-source GraphQL-first headless commerce (Python/Django) with native webhooks — compare against Bagisto's Laravel/event model./sales-spree— Open-source (BSD-3) headless commerce on Ruby on Rails with REST APIs and native outbound webhooks — compare if your team is choosing between the Ruby and PHP/Laravel stacks./sales-shopify— The leading hosted commerce backend; compare against Bagisto's self-hosted/open-source model./sales-merchant-of-record— Whether to use a MoR (Paddle, Lemon Squeezy) for global tax instead of self-managing (Bagisto is not a MoR)./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: Pull all orders into a warehouse via the API (developer/automation)
User: "I'm writing a script to sync every Bagisto order into BigQuery nightly. What auth do I use and how do I page through them?"
Approach: Use the Admin REST API. Authenticate with a Laravel Sanctum bearer token (Authorization: Bearer {token}) obtained from the admin login endpoint, and send Accept: application/json. Call GET /api/admin/orders?page=1&per_page=50 (per-page is capped at 50) and walk pages using the response headers X-Total-Pages / X-Total-Count / X-Page. There's no documented hard rate limit, so still throttle politely and back off on errors. If you're on the GraphQL package instead, query orders under the Admin API and page with Relay cursors (first/after + pageInfo).
Example 2: Notify a CRM when an order is placed (developer/automation)
User: "Where do I add a webhook URL in Bagisto so my CRM gets pinged on every new order?"
Approach: Explain Bagisto core has no outbound-webhook settings page. Because it's a Laravel app, register a listener on the checkout.order.save.after event (in a service provider's $listen map or an EventServiceProvider), load the order in the handler, and fetch()/Http::post() to your CRM — you own retries/signing/logging. Alternatives: a scheduled job that polls GET /api/admin/orders?per_page=50 for new IDs since the last run, or a community webhook package. Run a real queue worker so the outbound call doesn't block checkout.
Example 3: Self-host vs Bagisto Cloud
User: "Should I self-host Bagisto or use Bagisto Cloud? I'm a solo founder launching a small store." Approach: The engine is MIT/free with no per-sale fee either way — Cloud just sells managed infra. Self-hosting means you run PHP/Laravel + MySQL/MariaDB + Redis + a queue worker on a VPS (Railway/Render/DigitalOcean) and own updates, backups, and scaling. Bagisto Cloud (Starter vs Pro tiers — Pro adds a higher uptime SLA and advanced support) removes the ops burden. If they're comfortable with a LAMP+Redis stack and Laravel ops, self-host is cheapest; if not, Cloud is the lower-friction path. Match the choice to their infra appetite, not defaults — and note pricing should be re-verified on the live page.
Troubleshooting
"My product images are broken after install (or after moving the site)"
Set APP_URL in .env to the exact live URL (correct scheme and host), then run php artisan optimize:clear (or config:clear + cache:clear). Broken images and HTTPS "mixed content" warnings are almost always an APP_URL/scheme mismatch causing assets to load from the wrong origin. Confirm the storage symlink exists (php artisan storage:link).
"Pages take forever to load / the store is extremely slow"
Build caches (php artisan optimize, plus route/view/config caching), move cache & sessions to Redis, and run a queue worker so deferred work isn't done in-request. Category pages with bundle products are a known slow path — limit bundles per listing or cache the computed prices. If still slow, profile the DB and add indexes; very large catalogs benefit from the search/indexer being kept warm.
"I followed a tutorial but the API headers/endpoints don't exist"
You're likely mixing the two API generations. The current unified API uses /api/shop + /api/admin (REST) and /api/graphql (GraphQL) with X-STOREFRONT-KEY + Sanctum bearer auth. The older standalone bagisto/graphql-api (Mobikul) package uses a /graphql endpoint with JWT and an x-app-secret-key header. Check which package is in composer.json and read that package's docs specifically; install the REST/GraphQL package and run its php artisan ...:install if the routes are missing entirely.