PrestaShop 9 Admin API: Practical Guide for Developers
The new PrestaShop 9 Admin API is one of the most important architectural additions in the PrestaShop 9 generation.
It is designed to improve on the older Webservice API with a more modern security model, domain-oriented operations and an architecture that modules can extend.
The new API is built around:
- API Platform 3;
- OAuth2 authentication and authorization;
- CQRS commands and queries;
- scopes;
- OpenAPI/Swagger documentation;
- module-defined API resources.
This makes it particularly interesting for developers building:
- ERP integrations;
- PIM integrations;
- stock synchronization;
- supplier platforms;
- SaaS connections;
- order-management systems;
- reporting services;
- automation tools.
This guide explains the architecture, how authentication works, how to create clients, and how module developers can build on the API.
Version note: This article was verified on September 22, 2026 against the current PrestaShop 9 developer documentation. The Admin API is actively evolving, so always inspect the generated OpenAPI specification of the exact shop/version you integrate with.
Why PrestaShop Created a New Admin API
The older PrestaShop Webservice API is closely connected to legacy ObjectModel-style CRUD operations.
The PrestaShop project identifies several limitations of that older approach:
- limited permission and security management;
- basic CRUD behavior;
- legacy architecture;
- harder maintenance;
- tight relation to ObjectModel.
The new Admin API has different goals.
It is designed to be:
- more secure;
- easier to audit;
- more aligned with business actions;
- closer to modern standards;
- extendable by modules.
This is important.
A modern ecommerce API should not simply expose database records.
It should expose operations the business understands.
API Platform 3 Is the HTTP/API Foundation
PrestaShop 9 uses API Platform 3 for the new Admin API.
API Platform provides infrastructure for:
- routes;
- API resources;
- serialization;
- validation;
- OpenAPI generation;
- Swagger UI;
- providers;
- processors.
PrestaShop then integrates its own application architecture into that framework.
The result is not simply stock API Platform CRUD.
Core endpoints can call PrestaShop CQRS queries and commands.
CQRS: Reads and Writes as Business Operations
PrestaShop has used CQRS during its Symfony migration.
CQRS separates operations that:
read data
from operations that:
change state
The Admin API reuses that work.
According to the official architecture:
- a read operation can execute a CQRS query;
- a list operation can use a grid data factory;
- a write operation can execute a CQRS command.
This helps keep behavior consistent between the Back Office and API.
Why CQRS Matters
Imagine two possible ways to change a product.
Direct database approach
API request
→ UPDATE ps_product ...
This may bypass:
- validation;
- hooks;
- domain rules;
- related entities.
Application command approach
API request
→ API resource
→ CQRS command
→ application handler
→ domain rules
The second model is usually easier to keep consistent with the rest of the application.
It also makes API behavior easier to test.
The Admin API Is Enabled by Default
The current official PrestaShop documentation states that the Admin API is available out of the box in PrestaShop 9.
You still need to configure API clients and permissions before an external application can use it.
The Back Office path for client management is:
Advanced Parameters
→ Admin API
From there, administrators can create API clients and assign scopes.
Production Requires HTTPS
PrestaShop's Admin API enforces secure access in production.
Development mode can relax the HTTPS check for local work, but production use requires secure HTTPS.
Do not build an integration that depends on disabling transport security.
API credentials and tokens are sensitive.
They should never travel over plain HTTP on a production network.
OAuth2 Is the Authentication Model
The Admin API uses OAuth2.
OAuth2 separates several concepts:
- client;
- resource server;
- authorization server;
- access token;
- scopes.
In the default PrestaShop setup:
External application = client
PrestaShop = resource server
PrestaShop = authorization server
PrestaShop can also work with an external authorization server.
Client Credentials for Server-to-Server Integrations
For normal machine-to-machine integrations, PrestaShop documentation recommends the OAuth2 Client Credentials workflow.
Typical examples:
- ERP → PrestaShop;
- PIM → PrestaShop;
- WMS → PrestaShop;
- SaaS service → PrestaShop.
There is no human login in each API request.
The integration receives:
client_id
client_secret
and exchanges those for an access token.
Create an API Client in the Back Office
Go to:
Advanced Parameters
→ Admin API
→ Add new API Client
The client configuration includes fields such as:
- client name;
- client ID;
- description;
- lifetime;
- enabled status;
- scopes.
Use a descriptive client name.
Good:
Warehouse stock synchronization
Weak:
api2
Months later, administrators should immediately know what the credential is for.
Save the Client Secret Immediately
The PrestaShop Admin API documentation warns that the generated client secret is shown once.
Save it securely when the client is created.
Do not place it in:
- source control;
- public configuration;
- issue trackers;
- screenshots;
- logs.
Use an environment secret or dedicated secret-management system where available.
Create API Clients from CLI
PrestaShop also provides a console command:
bin/console prestashop:api-client create CLIENT_ID
For example:
bin/console prestashop:api-client create warehouse-sync
Additional options allow configuration of:
- name;
- description;
- scopes;
- token lifetime.
The documentation also exposes an --all-scopes option, but warns against using all scopes for real production integrations.
Use Least Privilege
Each API client should have only the scopes it requires.
A stock synchronization service may need product or stock-related access.
It should not automatically receive permissions to:
- manage unrelated modules;
- edit every API client;
- access unrelated customer operations.
If one token is stolen, limited scopes reduce the potential damage.
One Integration, One Client
Avoid using the same API client for:
- ERP;
- CRM;
- marketing automation;
- warehouse;
- reporting.
Give each service its own client.
Benefits:
- separate credentials;
- separate scopes;
- individual revocation;
- better auditability.
If the marketing platform is compromised, you can revoke only that client.
Getting an Access Token
With PrestaShop's internal authorization server, the token endpoint is:
/admin-api/access_token
The official documentation uses a request similar to:
curl --location 'https://shop.example.com/admin-api/access_token' \
--form 'grant_type="client_credentials"' \
--form 'client_id="warehouse-sync"' \
--form 'client_secret="YOUR_CLIENT_SECRET"' \
--form 'scope[]="product_read"' \
--form 'scope[]="product_write"'
The authorization server returns an access token.
The application then uses that token in API requests.
Send the Bearer Token
Authenticated requests use:
Authorization: Bearer YOUR_ACCESS_TOKEN
For example:
curl --location \
'https://shop.example.com/admin-api/api-client/infos' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
The exact available endpoints depend on the installed PrestaShop version and enabled modules.
Do not hard-code assumptions from a blog article.
Use the generated API documentation from the target shop.
Scopes Are Part of the Token Request
An important OAuth detail is that the client may be allowed to use many scopes, but the access token is issued for the scopes requested.
For example:
client allows:
product_read
product_write
customer_group_read
A specific token could request only:
product_read
That token then has narrower capability.
This is useful for reducing privilege further.
Missing Scope Returns an Authorization Error
If an endpoint requires a scope your token does not contain, PrestaShop returns an authorization error.
This is exactly what you want.
An integration should fail clearly rather than silently performing an operation outside its permissions.
Handle HTTP status codes explicitly in your API client.
Access Tokens Expire
API client configuration includes a token lifetime.
Applications should expect access tokens to expire.
Do not treat an access token as a permanent credential.
A robust client:
- obtains a token;
- caches it securely;
- tracks expiration;
- requests a new one when necessary.
Do not request a new token before every single API call unless your architecture genuinely requires that behavior.
PrestaShop Is Always the Resource Server
PrestaShop documentation makes a useful distinction.
The shop is always the resource server serving protected resources.
The authorization server can be:
- PrestaShop itself;
- an external authorization server.
This allows more advanced organizations to integrate central identity infrastructure where necessary.
External Authorization Servers
PrestaShop's architecture supports external authorization providers.
This can be useful in larger environments already using centralized OAuth infrastructure.
The official documentation provides integration concepts and an example involving an external authorization server.
This is more complex than the default internal flow.
Use it when your infrastructure has a genuine need for centralized authorization.
Swagger Documentation
One of API Platform's major benefits is automatic documentation.
PrestaShop exposes Swagger/OpenAPI information that developers can use to explore the API.
In a development environment, the Back Office provides a link to Swagger.
This is extremely useful because the Swagger page represents the API exposed by the actual installation.
OpenAPI JSON
The Admin API documentation can be exposed in OpenAPI format.
The official documentation references:
/admin-api/docs.json
This specification can be imported into tools such as:
- Postman;
- Insomnia-compatible clients;
- OpenAPI code generators.
This is much safer than manually maintaining a list of endpoint structures in another project.
Generate API Documentation from CLI
PrestaShop also provides:
php bin/console prestashop:generate:apidoc
The output can be redirected:
php bin/console prestashop:generate:apidoc > api-spec.json
Use cases include:
- API documentation;
- client generation;
- version comparison;
- contract testing;
- CI.
Version-Control the API Specification
For a large integration, store generated OpenAPI specifications for supported PrestaShop versions.
Then compare releases.
For example:
prestashop-9.0-api.json
prestashop-9.1-api.json
A diff can reveal:
- new endpoints;
- changed fields;
- new required values.
This makes compatibility work proactive.
Modules Can Add API Resources
The new API is designed for module extensibility.
PrestaShop scans API resource classes from modules when the expected convention is followed.
The documented module location is:
src/ApiPlatform/Resources
This allows a module to add its own API resources.
The endpoint is usable when the module is installed and enabled.
Modules Can Define Their Own Scopes
Module-defined API functionality should have its own permissions.
Examples:
security_audit_read
security_audit_write
supplier_import_read
supplier_import_run
This is better than requiring broad generic access.
A SaaS connector can receive exactly the capabilities it needs.
API Resources Use PHP Attributes
PrestaShop's API Platform integration uses PHP attributes for resource configuration.
That keeps endpoint configuration near the DTO/resource class.
Conceptually:
#[ApiResource(
operations: [
// API operation definitions
]
)]
class ExampleResource
{
// fields
}
PrestaShop also provides custom CQRS-oriented operations for connecting resources to commands and queries.
Providers Handle Reads
For CQRS-integrated API resources, Provider abstractions handle read operations.
PrestaShop includes providers for:
- single-resource queries;
- lists/grid data.
The provider receives the API resource configuration, transforms data into the required query and dispatches it.
Processors Handle Writes
Write operations use processor abstractions.
Requests such as:
- POST;
- PUT;
- PATCH;
- DELETE;
can be connected to CQRS commands.
This creates a clean path:
HTTP request
→ API resource
→ processor
→ CQRS command
→ command bus
→ handler
Why This Is Useful for Commercial Modules
Imagine a supplier-import module.
The Back Office needs:
- queue status;
- start import;
- retry failures;
- read supplier state.
A SaaS dashboard may need the same operations.
Instead of building separate ad-hoc endpoints such as:
/modules/mymodule/run.php?secret=...
the module can align with the Admin API architecture.
That gives you:
- OAuth2;
- scopes;
- consistent API documentation;
- framework routing;
- standard responses.
Do Not Turn Every Long Job into One API Request
The Admin API does not remove the need for queues.
A request like:
POST /admin-api/import-all-products
should not remain open for two hours while 100,000 products are processed.
A better model:
POST /imports
→ 202 Accepted
→ job ID
Then:
GET /imports/{id}
can return status.
The worker runs separately.
Design Asynchronous Operations
For large processes:
API
→ create job
→ queue
→ worker
→ progress
This gives the API predictable latency.
The integration can poll status or receive a webhook if your module implements one.
Make Writes Idempotent
Networks fail.
Clients retry.
Suppose an integration sends:
create supplier product mapping
and receives a timeout after the server already completed the operation.
If retrying creates another mapping, you now have duplication.
Use:
- stable external IDs;
- uniqueness constraints;
- idempotency keys where appropriate.
A safe retry should not produce a second business effect.
Rate-Limit Expensive Operations
Even authenticated clients can accidentally overload a shop.
A programming error can send thousands of requests per second.
Protect expensive custom endpoints with:
- sensible pagination;
- batch limits;
- rate limiting where appropriate.
Do not expose an endpoint that returns 500,000 fully hydrated products in one response.
Paginate Lists
API list operations should be bounded.
Prefer:
page
limit
filters
over:
give me the entire catalog
For synchronization, incremental reads are usually more efficient.
Use Incremental Synchronization
If an external reporting system already knows yesterday's catalog, it should not download the entire catalog every hour.
Use:
- modified timestamps;
- cursors;
- external event IDs;
- domain-specific checkpoints.
This reduces:
- API traffic;
- CPU;
- database load.
Handle HTTP Errors Explicitly
Your integration should distinguish:
- 400 validation error;
- 401 authentication problem;
- 403 missing scope;
- 404 missing resource;
- 409 conflict where applicable;
- 429 rate limit if introduced by your infrastructure;
- 5xx server failure.
Do not retry every error.
A missing required field will not become valid after ten retries.
Log Correlation IDs
For complex integrations, assign a request or job correlation ID.
Logs can then connect:
external request
→ API request
→ CQRS command
→ background job
→ supplier call
This dramatically simplifies support.
Never Log Secrets
Do not log:
- client secret;
- full bearer token;
- authorization headers.
Sanitize request logs.
If debug tooling captures complete HTTP requests, ensure access is restricted and retention is short.
Rotate Credentials
Prepare a process for client-secret rotation.
Do not wait until a suspected compromise.
A mature integration can:
- create a replacement client;
- deploy new secret;
- verify traffic;
- disable old client.
Separate clients make this easy.
Admin API vs Legacy Webservice
The legacy Webservice still exists in the broader PrestaShop ecosystem, but the new Admin API is the modern architecture introduced with PrestaShop 9.
For new integrations, evaluate the Admin API first.
Reasons include:
- OAuth2;
- scopes;
- API Platform;
- CQRS;
- module extensibility;
- generated OpenAPI documentation.
Do not rewrite a stable legacy integration merely for fashion.
But avoid expanding legacy technical debt when the modern API already fits the requirement.
Suggested Integration Architecture
A production integration may look like:
ERP / PIM
↓
OAuth2 token
↓
PrestaShop Admin API
↓
CQRS
↓
Business logic
↓
Database
Large tasks:
API → queue → worker
The API is the boundary.
The queue handles long work.
Security Checklist
- HTTPS in production
- One API client per integration
- Least-privilege scopes
- Secrets stored securely
- Tokens not logged
- Token expiration handled
- Old clients disabled
- Input validated
- Large operations asynchronous
- API errors monitored
Development Checklist
- Inspect current Swagger
- Export OpenAPI spec
- Test required scopes
- Test expired token
- Test invalid token
- Test missing scope
- Test validation errors
- Test retries
- Test pagination
- Test module disabled state
Frequently Asked Questions
Is the PrestaShop 9 Admin API enabled by default?
Yes. Current official documentation says it is available out of the box in PrestaShop 9, but clients and scopes must still be configured.
What authentication does the Admin API use?
OAuth2.
Which grant should a server-to-server integration use?
PrestaShop documentation recommends the Client Credentials flow for server-to-server integrations.
What framework powers the Admin API?
API Platform 3.
Does the Admin API use CQRS?
Yes. PrestaShop integrates API resources with existing CQRS commands and queries.
Where do I create an API client?
In the Back Office under Advanced Parameters → Admin API, or through the prestashop:api-client console command.
What is the access-token URL?
With the internal authorization server, the documented endpoint is /admin-api/access_token.
Can modules add endpoints?
Yes. Module extensibility is a core design goal of the new API. Module resources can be loaded from src/ApiPlatform/Resources.
Is Swagger available?
Yes. API Platform generates API documentation, and PrestaShop provides Swagger/OpenAPI access for the Admin API.
Should I give an integration all scopes?
No. PrestaShop documentation explicitly recommends limiting each client to the minimum scopes required.