E-Commerce API Example
Complete GraphQL API documentation for an e-commerce platform with products, orders, customers, OAuth2 authentication, and real-time order tracking.
This example demonstrates a complete e-commerce GraphQL API with product catalogue, order management, and customer accounts. It showcases JWT authentication, custom scalars (DateTime, Money, EmailAddress), and real-time subscriptions for inventory and order tracking.
API Overview
The E-Commerce API provides:
- Products - Catalogue browsing with filtering and Relay-style pagination
- Orders - Order creation, retrieval, and status management
- Customers - Account management and order history
- Real-time Updates - Inventory and order status subscriptions
API Definition
The complete API definition includes servers, authentication schemes, custom scalars, directives, and interfaces.
A comprehensive GraphQL API for e-commerce operations including products, orders, customers, and real-time inventory updates. This API follows the Relay specification for pagination and implements standard GraphQL best practices.
Query Operations
Query operations retrieve data from the catalogue and order system.
Retrieves a paginated list of products with optional filtering. Supports Relay-style cursor-based pagination.
Retrieves a single product by its unique identifier. Returns null if the product does not exist or has been discontinued.
Retrieves all product categories. This is a lightweight query that returns the category hierarchy for navigation purposes.
Retrieves a single order by its unique identifier. Users can only access their own orders unless they have administrative privileges.
Retrieves a single customer by their unique identifier. Requires authentication and appropriate permissions.
Retrieves a paginated list of customers. Restricted to administrative users only.
Retrieves all orders for a specific customer, optionally filtered by status. Useful for order history views.
Mutation Operations
Mutations create and modify data in the system.
Creates a new order for a customer. The order is initially created in PENDING status and must have at least one item. Stock is reserved upon order creation.
Creates a new customer account. The email address must be unique. A welcome email is sent upon successful creation.
Creates a new product in the catalogue. Requires administrative privileges. The product is created in DRAFT status by default.
Updates an existing product. Only provided fields are updated; omitted fields retain their current values.
Updates the status of an order. Valid transitions are: PENDING→CONFIRMED→SHIPPED→DELIVERED or PENDING→CANCELLED. Returns the updated order with status history.
Adds a new item to an existing order. Only orders in PENDING status can be modified. Stock is reserved for the added item.
Subscription Operations
Subscriptions provide real-time updates via WebSocket connections.
Subscribes to real-time order status updates for a specific order. Emits an event whenever the order status changes, including the new status, previous status, and timestamp.
Subscribes to real-time inventory updates for a specific product or all products. Emits events when stock quantities change due to orders, restocking, or manual adjustments.
Subscribes to real-time notifications when new orders are created. Useful for order management dashboards and fulfilment systems. Can optionally filter by customer ID.