nshop/packages/Webkul/BagistoApi

、# Bagisto API Platform

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

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:

• REST API Docs: https://your-domain.com/api/docs
• GraphQL Playground: https://your-domain.com/graphql

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

return [
    // ...existing providers...
    Webkul\BagistoApi\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

# Install required packages
composer require api-platform/laravel:v4.1.25
composer require api-platform/graphql:v4.2.3

Step 5: Run the installation

php artisan bagisto-api-platform:install

Step 9: 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:

• REST API (Shop): https://your-domain.com/api/shop/
• REST API (Admin): https://your-domain.com/api/admin/
• GraphQL Endpoint: https://your-domain.com/graphql`
• GraphQL Playground: https://your-domain.com/graphqli

Payment Flow

The payment pipeline supports two paths through a single set of GraphQL mutations:

1. Standard checkout – buyer fills address/email/shipping method before payment. Order is created with full tax/shipping totals.
2. Express checkout – buyer skips address/email entirely. Order is created with placeholder address and tax_amount = shipping_amount = 0; the gateway response fills the buyer's real address on success.

Both paths use the same state machine:

+----------------+   paymentInitiate    +----------+   paymentCallback
|  cart token    |  ─────────────────▶  | order(PENDING)|  ───────────▶ order(PROCESSING)
+----------------+                       +----------+                   (success)
                                              │
                                              │   paymentReplay
                                              │   (re-issue gateway order id)
                                              ▼
                                          cancelOrder ── strategy ──▶ cancel / keep_pending

Mutations

Mutation	Purpose
paymentInitiateCreate	Create the Bagisto order + a gateway order id in one shot. Returns the new cart token so the buyer can keep adding products to a fresh cart. Set expressCheckout: true to skip shipping/email validation.
paymentCallbackCreate	Frontend hits this after the gateway redirect. status = success triggers capture + (for express orders) writes the real shipping/billing address. `status = cancel
paymentReplayCreate	Authenticated. Generates a fresh gateway order id for a still-pending order so the buyer can retry payment.
cancelOrderCreate	Existing mutation; now strategy-aware: guest cancels immediately and reactivates the old cart; customer with shipping address stays pending; customer without shipping address follows the bagistoapi.express_checkout.cancel_without_address config (cancel by default, switchable to keep_pending).

payment.additional keys

paymentInitiateCreate stores the following keys onto the order's payment record so callbacks and the reconciliation job can pick the right branch:

• express – boolean; true for express-checkout orders.
• gateway_order_id – same value as paypal_order_id (kept for parity).
• paypal_order_id – PayPal order id when the gateway is Smart Button.
• cart_id – original cart id, used when reactivating a cart.
• cart_token – original guest cart token (guest carts only).

Dead-letter reconciliation

Each successful paymentInitiate enqueues ReconcilePendingPaymentJob on the bagistoapi.reconcile.queue queue with a configurable delay (bagistoapi.reconcile.delay_minutes, default 15 min). The job:

• exits cleanly if the order is no longer pending;
• if the gateway reports a capture, dispatches bagistoapi.payment.reconcile.captured so ops can investigate a missed callback (likely a network failure on the client side);
• otherwise calls OrderRepository::cancel($order) and dispatches bagistoapi.payment.reconcile.cancelled.

Route the queue to a dead-letter capable broker (e.g. RabbitMQ) via the standard Laravel queue config; the job itself is broker-agnostic.

Extension events

The flow emits the following events that listeners can subscribe to:

• bagistoapi.payment.initiated – after order + gateway order created.
• bagistoapi.payment.success – after a successful capture.
• bagistoapi.payment.cancelled – cancel callback received.
• bagistoapi.payment.replayed – new gateway order issued for pending order.
• bagistoapi.express.cancel.no-address – customer cancels an express order that still has the placeholder address; config decides whether to actually cancel.
• bagistoapi.order.cancel.kept-pending – cancel mutation kept the order pending instead of cancelling.
• bagistoapi.payment.reconcile.captured – reconciliation found a capture on the gateway side but Bagisto is still pending.
• bagistoapi.payment.reconcile.cancelled – reconciliation cancelled the order.
• bagistoapi.payment.reconcile.voided – reconciliation found the gateway order in a terminal failed state.
• bagistoapi.payment.reconcile.no-gateway-info – reconciliation found no gateway info on the order; surfaced for monitoring.

Configuration

config/bagistoapi.php (publish via php artisan vendor:publish --tag=bagistoapi-config):

'express_checkout' => [
    'enabled'                => env('BAGISTOAPI_EXPRESS_CHECKOUT_ENABLED', true),
    'cancel_without_address' => env('BAGISTOAPI_EXPRESS_CANCEL_WITHOUT_ADDRESS', 'cancel'),
    'placeholder_address'    => [/* address used pre-payment */],
],
'reconcile' => [
    'enabled'        => env('BAGISTOAPI_PAYMENT_RECONCILE_ENABLED', true),
    'delay_minutes'  => (int) env('BAGISTOAPI_PAYMENT_RECONCILE_DELAY', 15),
    'queue'          => env('BAGISTOAPI_PAYMENT_RECONCILE_QUEUE', 'payment-reconcile'),
],

Documentation

• Bagisto API: Demo Page
• API Documentation: Bagisto API Docs
• GraphQL Playground: Interactive Playground

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.