Bagisto API Platform

Comprehensive REST and GraphQL APIs for seamless e-commerce integration and extensibility.

Requirements

• PHP 8.3+
• Bagisto v2.4.x — tested in CI against v2.4.10, and supported on the 2.4 releases before it (see Bagisto Compatibility)
• Composer 2
• MySQL 8.0+ or PostgreSQL 14+
• API Platform for Laravel — api-platform/laravel and api-platform/graphql (~4.3.8), which bring in the remaining api-platform/* components at a matching version, installed automatically via composer require

Bagisto Compatibility

One package serves the whole 2.4 line. It detects what the store it is installed on can do, so most of the API is identical everywhere and only the theme surface follows the store.

Only one set is registered, so endpoints the store cannot support are absent rather than failing when called. A few smaller behaviours follow the store the same way: product image alt_text, the derived columns behind the product listing, attribute regex validation, the attribute-family delete guard, and the in-use guards on email templates and marketing events.

Upgrading Bagisto is what moves the theme endpoints — the package itself needs no change. Rebuild the caches afterwards so the new surface is picked up:

php artisan bagisto-api-platform:optimize

Installation

Method 1: Quick Start (Composer Installation – Recommended)

The fastest way to get started:

composer require bagisto/bagisto-api
php artisan bagisto-api-platform:install

Your APIs are now ready! Access them at:

• API Landing: https://your-domain.com/api
• REST API Docs (Shop): https://your-domain.com/api/shop/docs
• REST API Docs (Admin): https://your-domain.com/api/admin/docs
• GraphQL Playground (Shop): https://your-domain.com/api/graphiql
• GraphQL Playground (Admin): https://your-domain.com/api/admin/graphiql

Method 2: Manual Installation

Use this method if you need more control over the setup.

Step 1: Download and Extract

1. Download the BagistoApi package from GitHub
2. Extract it to: packages/Webkul/BagistoApi/

Step 2: Register Service Provider

Edit bootstrap/providers.php:

<?php

// ...existing imports...
use Webkul\BagistoApi\Providers\BagistoApiServiceProvider;
// ...rest of imports...

return [
    // ...existing providers...
    BagistoApiServiceProvider::class,
    // ...rest of providers...
];

Step 3: Update Autoloading

Edit composer.json and update the autoload section:

{
  "autoload": {
    "psr-4": {
      "Webkul\\BagistoApi\\": "packages/Webkul/BagistoApi/src"
    }
  }
}

Step 4: Install Dependencies

composer require -W \
  api-platform/laravel:~4.3.8 \
  api-platform/graphql:~4.3.8 \
  "symfony/property-access:^7.0" \
  "symfony/property-info:^7.1" \
  "symfony/serializer:^7.4.9" \
  "symfony/type-info:^7.3" \
  "symfony/validator:^7.0" \
  "symfony/web-link:^7.4"

Step 5: Run the installation

php artisan bagisto-api-platform:install

Step 6: Environment Setup (Update in the .env)

STOREFRONT_DEFAULT_RATE_LIMIT=100
STOREFRONT_CACHE_TTL=60
STOREFRONT_KEY_PREFIX=storefront_key_
STOREFRONT_PLAYGROUND_KEY=pk_storefront_xxxxxxxxxxxxxxxxxxxxxxxxxx 
API_PLAYGROUND_AUTO_INJECT_STOREFRONT_KEY=true

Access Points

Once verified, access the APIs at:

• API Landing: https://your-domain.com/api
• REST API (Shop): https://your-domain.com/api/shop/
• REST API (Admin): https://your-domain.com/api/admin/
• REST API Docs (Shop): https://your-domain.com/api/shop/docs
• REST API Docs (Admin): https://your-domain.com/api/admin/docs
• GraphQL Playground (Shop): https://your-domain.com/api/graphiql
• GraphQL Playground (Admin): https://your-domain.com/api/admin/graphiql

Exporting the API Schema

Generate schema files for the shop and admin APIs — OpenAPI JSON (REST) and GraphQL SDL — to import into Postman, a client/code generator, or a mock server without calling a live server:

php artisan bagisto-api-platform:export-schema

The files are written to schema/generated/:

Each spec is scoped to its own surface — the storefront spec carries no admin path, schema or tag, and the reverse — and the command refuses to write one that leaks the other surface or references a definition it does not include.

Options:

• --path=<dir> — write elsewhere
• --transport=all|rest|graphql — limit to one transport (default all)

Re-running overwrites those six files and nothing else. To rebuild the Postman collections from them:

php schema/tools/build-collection.php

Postman Collections

Run them from the public workspace, or import the copies that ship with the package:

• collections/Bagisto-Shop-API.postman_collection.json — storefront: browsing, cart, checkout, orders, account
• collections/Bagisto-Admin-API.postman_collection.json — admin, foldered to mirror the admin sidebar
• environments/Bagisto.postman_environment.json — one environment for both

Both transports are covered: requests are foldered REST/ and GraphQL/ under the same resource names, with GraphQL split into Queries/ and Mutations/.

Importing

1. Postman → Import → pick a file from collections/.
2. Postman → Environments → Import → pick environments/Bagisto.postman_environment.json, select it, then fill in your values.

Fill in only what the collection you are using needs.

Authenticating

Shop — run REST → Customer → Customer login. It stores customerToken, which every other request sends as the bearer. For a guest cart, run Create cart token instead and set the collection's Authorization tab to {{cartToken}}; the cart and checkout endpoints serve guests and logged-in customers alike, so the token you send decides whose cart you are working on.

Admin — there is no login request. Generate an integration token in the admin panel (see Admin API Authentication) and paste it into adminToken.

Keeping them current

schema/tools/build-collection.php regenerates the collections from the exported schemas, so a collection follows the API rather than being maintained by hand. After bagisto-api-platform:export-schema writes a new schema, rerun the builder and commit both — Validate rebuilds the collections in CI and fails the push if the committed copies no longer match, so a stale collection cannot reach the workspace.

Three workflows keep the published copies in step: Validate checks the files and that rebuild on every push, Push Collections to Postman publishes them to the official workspace when they change on main, and Sync Collections from Postman pulls edits made in Postman back into the repository on a release. All three refuse to move a real storefront key.

Publishing needs four repository secrets, and the push and sync jobs skip with a notice while any of them is missing rather than failing the build:

Collection and environment UIDs come from Postman — open the item, then Info → ID. Validation needs no secret and runs on every push regardless.

Values in the requests are placeholders — replace them with records that exist on your store. Postman's Auto Fetch runs a schema introspection query that costs far more than a normal request; switch it off if the GraphQL folders feel slow.

Admin API Authentication

Admin endpoints (/api/admin/* and /api/admin/graphql) require an integration-token Bearer header:

Authorization: Bearer id|generated-token

To generate a token:

1. Log into the Bagisto admin panel.
2. Enable the module first: navigate to Configuration → API → Integration → Module Settings and turn Enabled on. (Without this, the Integration menu stays hidden.)
3. Navigate to Settings → Integration.
4. Click Create, fill in the name / description / assigned admin / permission mode (All, Custom, or Same as Web) / optional IP allowlist / rate limits / expiry, and save as a draft.
5. Click Generate. The plaintext token is shown once — copy it immediately. You won't be able to view it again; if lost, use Regenerate to issue a new one.

Each token is scoped to a single admin user and inherits that admin's role permissions — so tokens can never do more than their owner could in the admin UI. To issue tokens to multiple admins, create one token per admin (each admin can hold only one active token at a time).

Tokens can be revoked at any time from the same page or via the signed link in the lifecycle notification email sent to the token owner.

Documentation

• Bagisto API: Demo Page
• API Documentation: Bagisto API Docs
• GraphQL Playground (Shop): Interactive Playground
• GraphQL Playground (Admin): Interactive Playground
• Release history: see CHANGELOG.md

Support

For issues and questions, please visit:

• GitHub Issues
• Bagisto Documentation
• Community Forum

📝 License

The Bagisto API Platform is open-source software licensed under the MIT license.