- What is aimeos/aimeos-headless and when should I use it?
- It is a cloud-native, API-first ecommerce distribution built on Laravel that exposes JSON REST endpoints for product catalogs, categories, carts, checkout, orders, customers, and admin operations. You should use it when you want a decoupled commerce core behind a custom web, mobile, partner, or marketplace frontend instead of a ready-made storefront. It fits teams already running Laravel/PHP or willing to operate a dedicated PHP commerce service. It is a weaker fit for pure Node, Java, or .NET platforms unless you plan for a separate PHP runtime and its operational ownership.
- How do I install aimeos/aimeos-headless with Composer in a Laravel app?
- Install it via Composer into a Laravel application or provision it as a standalone Laravel-based service, then run the migrations and publish the configuration. Expect follow-up configuration for database, cache, queue workers, search engine, object storage, and CORS before the API is usable. Verify PHP extensions and dependency constraints against your Laravel version first. Treat the API contract and extension points as part of the setup review, not an afterthought.
- Does Aimeos Headless include a storefront or frontend?
- No. Aimeos Headless is an API-first commerce backend, so it ships the commerce engine and JSON REST endpoints rather than a ready-made shop frontend. You bring your own frontend, such as a Next.js, Vue, mobile, or partner portal app, and consume the catalog, cart, checkout, and order APIs. Frontend compatibility is genuinely API-only, so plan your BFF or API gateway layer accordingly.
- Which PHP and Laravel versions does aimeos/aimeos-headless support?
- Version support moves with Aimeos and Laravel releases, so confirm the exact PHP and Laravel constraints from the package's composer.json and documentation for the release you intend to use. Check required PHP extensions, database and search engine versions, Redis and queue configuration, and storage permissions at the same time. Pin dependency versions and define a contract test suite for the endpoints your frontend and integrations rely on. This reduces surprises during Laravel and Aimeos upgrades.
- Can I use Aimeos Headless for a B2B shop or a marketplace?
- Yes. The package is positioned for B2B applications and scalable marketplaces as well as D2C and multi-channel commerce. The real work is in the commerce domain model: pricing, tax, promotions, stock, order states, B2B rules, and marketplace splits. Validate how deep those rules can be customized in Aimeos before committing, and pilot one channel, region, or catalog segment first.
- How do authentication and authorization work for customers, admins, and partners?
- Aimeos Headless exposes API endpoints, so auth is typically handled with Laravel's auth stack, token-based access, and roles or scopes at the API gateway or BFF layer. You must define separate models for customers, admins, and partner or marketplace sellers, including token scopes, rate limits, and CORS policy. Confirm the required auth model during discovery rather than assuming the default setup covers partners or admin portals.
- How do I scale Aimeos Headless for large catalogs and high checkout traffic?
- Run it with MySQL or PostgreSQL, Redis for cache, queue workers for background jobs, Elasticsearch or OpenSearch for catalog search, S3-compatible storage, and containerized PHP-FPM behind a load balancer. Catalog scale and checkout concurrency are the two areas to stress first, especially inventory correctness under parallel checkout. Load, security, and failure testing should come before production cutover, followed by a feature-flagged pilot.
- What third-party systems can I integrate with the Aimeos REST API?
- You will typically integrate payment providers, tax engines, shipping and fulfillment, ERP, PIM, CRM, and search systems. The headless model makes frontend choice easier, but the commerce domain model is the real integration surface, so validate API contracts and extension points before committing. Where an existing ERP or order management system must remain the system of record, define explicit sync and reconciliation. Avoid a big-bang checkout cutover; a strangler approach with incremental migration is safer.
- How do I test and maintain Aimeos Headless without breaking production?
- Build a contract test suite around the endpoints your frontend and integrations depend on, and pin both dependency and API versions. Maintenance includes ongoing Composer updates, Laravel and Aimeos upgrades, database migrations, API versioning, plugin maintenance, and regression testing, so assign clear ownership for the commerce service and security patching. Customizations should be tracked against upstream changes to avoid upgrade friction. Confirm release cadence, issue responsiveness, license terms, and commercial support options before relying on it long term.
- What are the alternatives to Aimeos Headless and how does it compare?
- Alternatives include the full Aimeos Laravel shop package if you want a bundled storefront, plus other commerce platforms such as Sylius, Spree, Shopify, or commercetools depending on your stack. Aimeos Headless stands out for teams already invested in Laravel/PHP who want an API-first commerce core they can host and customize. Its community signal of roughly 2.6k GitHub stars is viable but not dominant, so weigh ecosystem size, support contracts, and total cost of ownership against your target use case. If your platform is non-PHP, isolate it as a separate commerce service behind an API gateway rather than embedding it.