PrestaShop platform help — open-source, self-hosted PHP/MySQL commerce platform for developers, agencies, and makers: products/combinations, orders, customers, carts, stock, taxes, CMS, multistore, and a 300+ feature back office extended by modules and a hook system. Its CRUD Webservice REST API sits at `/api/` with HTTP Basic auth (32-character key, empty password) and XML-or-JSON output. Use when enabling the Webservice and generating an API key, a call 401s because the Authorization header is stripped (CGIPassAuth/.htaccess), building a product/order/stock sync to a CRM or warehouse, reacting to a new order when there are no native webhooks (module hook, a Webhooks module, or polling), a 1-Click or PHP-8 upgrade breaking overrides/modules, or choosing PrestaShop Classic vs Hosted vs Shopify/WooCommerce/OpenCart/Magento. Do NOT use for cross-cart checkout-conversion strategy (use /sales-checkout) or picking a Merchant of Record for global tax (use /sales-merchant-of-record).
Instrucciones de origen · Vista previa de solo lectura
name
sales-prestashop
description
PrestaShop platform help — open-source, self-hosted PHP/MySQL commerce platform for developers, agencies, and makers: products/combinations, orders, customers, carts, stock, taxes, CMS, multistore, and a 300+ feature back office extended by modules and a hook system. Its CRUD Webservice REST API sits at `/api/` with HTTP Basic auth (32-character key, empty password) and XML-or-JSON output. Use when enabling the Webservice and generating an API key, a call 401s because the Authorization header is stripped (CGIPassAuth/.htaccess), building a product/order/stock sync to a CRM or warehouse, reacting to a new order when there are no native webhooks (module hook, a Webhooks module, or polling), a 1-Click or PHP-8 upgrade breaking overrides/modules, or choosing PrestaShop Classic vs Hosted vs Shopify/WooCommerce/OpenCart/Magento. Do NOT use for cross-cart checkout-conversion 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 PrestaShop — e.g. 'sync products in via the Webservice API' or 'notify my CRM on a new order without webhooks']
license
MIT
version
1.0.1
tags
["sales","checkout","ecommerce","platform"]
github
https://github.com/PrestaShop
PrestaShop Platform Help
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 — standing up a store, building/debugging a Webservice API integration, syncing products/orders/stock to a CRM or warehouse, reacting to an order event, a module/override/upgrade problem, or a platform-selection decision?
Surface — the Webservice REST API (/api/, CRUD over ~70 resources), a module + hook (for event push or custom logic), the admin back office UI, or a theme (Smarty)?
Auth — HTTP Basic with a 32-character key as username and an empty password; a 401 usually means the key's permissions are wrong or the Authorization header is being stripped (CGIPassAuth).
Hosting — Classic (self-hosted, you own PHP/MySQL + hosting) or Hosted / "Ready" (managed ~€29/mo)? Which PrestaShop version (1.6 / 1.7 / 8.x / 9.x) and PHP version?
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 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}
Comparing PrestaShop against another commerce backend at a high level
/sales-checkout {question} (platform selection)
Whether to use a Merchant of Record for global VAT/sales tax
/sales-merchant-of-record {question}
Post-purchase / abandoned-cart email sequences
/sales-email-marketing {question}
Selling one catalog across Amazon/eBay/Etsy/marketplaces
/sales-multichannel-selling {question}
Otherwise it's a PrestaShop-specific question — answer it here.
Step 3 — PrestaShop platform reference
Read references/platform-guide.md for the full reference — modules and what's
API-accessible vs UI-only, pricing/infra posture, data model with JSON shapes, and
quick-start recipes. For raw auth/endpoint/resource detail, read
references/prestashop-api-reference.md.
Answer using only the relevant section — don't dump the whole guide.
Step 4 — Actionable guidance
The API is a CRUD Webservice at /api/, XML by default. Enable it (Advanced Parameters → Web service → Yes), create a 32-char key with per-resource permissions, and call with HTTP Basic (key as username, empty password). Add output_format=JSON for JSON. GET /api/ lists every resource you can reach.
If every call 401s, it's almost always CGIPassAuth. Apache/PHP-FPM strips the Authorization header — add CGIPassAuth On (or the SetEnvIf Authorization fallback) to .htaccess. Otherwise check the key's per-resource rights.
Reads trim + filter; writes are XML and PUT is a full replace. Use display=[…], filter[field]=… (OR [a|b], interval [min,max], %pattern%), sort=[field_ASC], limit=start,count (offset paging — no cursor). Create from ?schema=blank; PUT replaces the whole entity (GET→mutate→PUT); set stock via stock_availables, not products.
There are no native outbound webhooks. To push on a new order, write a small module that registers a hook (actionValidateOrder, actionOrderStatusUpdate) and cURLs out (add your own HMAC), install a third-party Webhooks module, or poll orders. Keep hook handlers fast — they run in-process during checkout.
It's self-host: infra and upgrades are yours. Match the PHP version to the PrestaShop version, keep overrides thin, and test the 1-Click Upgrade on staging — third-party modules/overrides are what break on major upgrades. Not a Merchant of Record — you own tax.
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-07) — re-verify the resource list/verbs, auth behaviour, pricing, and PHP/version compatibility against live docs.
401 on every call = stripped Authorization header. The classic cause is Apache/PHP-FPM dropping the header before PHP sees it. Add CGIPassAuth On to .htaccess (or SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1). Second cause: the key lacks permission on that resource/verb.
The key is the username; the password is empty. With cURL use -u "KEY:" (trailing colon). Never put the key in the URL for production — it leaks into logs/history.
No outbound webhooks in core. There is no "add a webhook URL" screen. Push events via a module hook, a 3rd-party Webhooks module, or poll — nothing signs the payload for you, so add your own secret/HMAC.
PUT replaces the entire entity. A partial PUT wipes unspecified fields. GET the full record, mutate, PUT it back (keep the <id>). Only some resources (stock_availables, warehouses) accept PATCH.
Stock isn't on the product. Quantity lives on stock_availables (or ASM warehouses/stock_movements) — updating products won't change what's sellable.
XML-first, per-language fields. Input is XML (JSON is output-only in practice); translatable fields (name, link_rewrite) are wrapped per <language id="…">, and slugs must be clean (lowercase/hyphenated) or you get validation errors.
Upgrades break modules/overrides. The 1.6→1.7 Symfony shift and PHP 7→8 deprecations (e.g. Tools::jsonEncode) leave third-party modules and heavy overrides throwing 500s. Test the 1-Click Upgrade on staging; keep overrides minimal.
Advanced Stock Management is optional.warehouses/supply_orders/stock_movements resources only exist when ASM is enabled.
Related skills
/sales-checkout — Checkout-conversion strategy across carts (order bumps, upsells, cart-abandonment recovery) and high-level platform selection.
WooCommerce — the other big self-hosted PHP store (WordPress plugin); compare data ownership, REST API + webhooks, and ecosystem. For cart-platform selection across tools, use /sales-checkout.
/sales-bagisto — Open-source Laravel/PHP commerce framework — the other PHP-stack option; also no native outbound webhooks (Laravel events instead of PrestaShop hooks).
/sales-shopify — The leading hosted commerce backend — compare against PrestaShop's self-hosted/open-source model and infra ownership.
/sales-merchant-of-record — Whether to use a MoR (Paddle, Lemon Squeezy) for global tax instead of self-managing (PrestaShop 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: Sync a product catalog in via the Webservice API (developer/automation)
User: "I'm writing a nightly script to push products and stock into PrestaShop. Which API and how do I authenticate?"
Approach: Use the Webservice at /api/. Enable it (Advanced Parameters → Web service), generate a 32-char key, and grant it GET/POST/PUT on products, combinations, and stock_availables. Authenticate with HTTP Basic — key as username, empty password (curl -u "KEY:"). To create, GET products?schema=blank, fill the XML (price, reference, and name/link_rewrite per <language>), and POST it; to update, GET the full record, mutate, and PUT it back (PUT replaces the whole entity). Set quantities on stock_availables, not on the product. If calls 401 despite a valid key, add CGIPassAuth On to .htaccess. Verify/export with output_format=JSON&display=[…].
Example 2: Notify a CRM when an order is placed without webhooks (developer/automation)
User: "Where do I add a webhook URL in PrestaShop so my CRM gets pinged on each new order?"
Approach: Explain there's no outbound-webhook screen in core. The reliable path is a small custom module that registers on actionValidateOrder (and actionOrderStatusUpdate for status changes) and cURLs a JSON payload to your CRM with an HMAC X-PS-Signature header. Because hooks run in-process during checkout, keep the call fast (short timeout) or enqueue it so a slow CRM never blocks the buyer. No-code alternatives: a third-party "Webhooks" module from Addons, or a Zapier/Make "new order" trigger. If you can't deploy code, pollorders?sort=[id_DESC]&filter[date_add]=[…] and track the last-seen id.
Example 3: Choose PrestaShop vs other self-hosted stores
User: "I'm a solo founder who can run a server. PrestaShop, WooCommerce, or Shopify for a small EU store?"
Approach: PrestaShop (Classic) is free, self-hosted PHP/MySQL with a 300+ feature back office, a big module marketplace, and a stable CRUD API — strong for EU merchants and anyone already in its ecosystem, but you own hosting, PHP-version matching, and upgrade pain (modules/overrides break on majors). WooCommerce wins if the store lives inside WordPress/content. Shopify is hosted (no infra, faster launch) but has platform + possible gateway fees and less data ownership. If they want zero-infra, lean Shopify; if they want control/no-per-sale-fee and can run PHP, PrestaShop or WooCommerce. For cross-cart conversion tactics or MoR-tax decisions, route to /sales-checkout or /sales-merchant-of-record. Re-verify pricing/versions before committing.
Troubleshooting
"Every Webservice call returns 401 Unauthorized"
Two usual causes. (1) Stripped auth header — Apache/PHP-FPM drops Authorization before PHP reads it, so the key never arrives. Add CGIPassAuth On to the shop-root .htaccess, or SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1. (2) Permissions — the key isn't granted that verb on that resource (Advanced Parameters → Webservice → your key → Permissions). Confirm the Webservice itself is enabled, use -u "KEY:" (key as username, empty password, trailing colon), and check the key Status is active.
"A PUT wiped fields / my product-create fails validation"
PUT /api/{resource}/{id} is a full replace, not a patch — any field you omit is cleared. Fetch the record with display=full, change only what you need, and PUT the entire document back (keep <id>). For create/validation errors ("… is not valid"), start from GET /api/{resource}?schema=synopsis to see required fields/format rules; the most common trip-ups are non-slug link_rewrite/reference (must be lowercase, hyphenated) and forgetting the per-<language> wrapper on translatable fields. Set stock on stock_availables, not products.
"After a 1-Click Upgrade my modules/back office throw 500 errors"
Major upgrades (1.6→1.7 Symfony migration, PHP 7→8) break third-party modules and overrides that use deprecated classes/functions (e.g. Tools::jsonEncode) or namespace assumptions. Always run the upgrade on a staging copy first, then: match the PHP version to the target PrestaShop version, disable overrides and re-enable them one at a time to isolate the culprit, update or replace incompatible modules, clear the cache (var/cache), and enable debug mode to read the real stack trace. Keep overrides thin so the next upgrade survives.
