Skip to main content

​
Overview

The GraphQL API provides a flexible alternative to REST endpoints for querying product listings, product details, banners, and navigation menus. The endpoint supports both GET and POST requests with query and variable parameters.

​
Endpoint

POST /api/v2/graphql
GET /api/v2/graphql

​
CMS GraphQL Endpoint

POST /api/v2/cms/graphql

​
Content Types

The GraphQL endpoint accepts three content types:
  • application/json - Standard JSON requests with query and variables
  • application/graphql - Raw GraphQL query strings
  • application/x-www-form-urlencoded - Form-encoded requests

​
Schema Overview

The GraphQL schema is built with Graphene and provides two main query types:

​
Main Schema

  • product - Fetch individual product details
  • listing - Query product listings with filtering and pagination

​
CMS Schema

  • productdetail - Fetch product detail page data
  • bannerurl - Query banner configurations
  • desktopnavmenu - Desktop navigation menu structure
  • mobilenavmenu - Mobile navigation menu structure

​
Query Examples

​
Fetch Product Listing

query ProductListing($filters: FilterInput, $page: Int, $size: Int, $sort: Sort) {
  listing(filters: $filters, page: $page, size: $size, sort: $sort) {
    products {
      id
      name
      price
      spl_price
      images
      sale_url
      tags
      category {
        id
        name
      }
    }
    total
    page
    size
    filters {
      categories
      tags
      artists
      priceRange
    }
  }
}

​
Fetch Single Product

query GetProduct($id: Int!) {
  product(id: $id) {
    id
    name
    description
    price
    spl_price
    images
    variants {
      id
      size
      color
      stock
    }
    category {
      id
      name
      parent_id
    }
  }
}

​
Fetch Product Detail Page (CMS)

query ProductDetailPage($sale_url: String!) {
  productdetail(sale_url: $sale_url) {
    id
    name
    description
    images
    seo {
      title
      description
      keywords
    }
  }
}

​
Filter Options

The listing query supports comprehensive filtering:
​
filters
FilterInput

​
Sort Options

Available sort values:
  • DEFAULT - Default sorting
  • PRICE_LOW_TO_HIGH - Price ascending
  • PRICE_HIGH_TO_LOW - Price descending
  • DISCOUNT_HIGH_TO_LOW - Discount descending
  • NEWEST_FIRST - Recently added products

​
Pagination

​
page
integer
default:"1"
Page number for pagination
​
size
integer
default:"10"
Number of products per page

​
Exclusive Pricing

The GraphQL resolver automatically detects exclusive users and applies exclusive pricing: 
# Exclusive user detection
is_exclusive_user = info.context['post_data'].get('is_exclusive_user', None)
if is_exclusive_user:
    price_list_ids = settings.EXCLUSIVE_PRICELISTS
Pass is_exclusive_user: true in your request body to enable exclusive pricing.

​
Caching

By default, GraphQL queries use cached results for improved performance. To bypass cache: 
{
  "query": "...",
  "use_cached_results": false
}

​
Error Handling

The GraphQL endpoint returns errors in the standard GraphQL format: 
{
  "errors": [
    {
      "message": "Must provide query string."
    }
  ]
}
Common errors:
  • Must provide query string - No query provided in request
  • Variables are invalid JSON - Malformed variables parameter
  • POST body sent invalid JSON - Invalid request body

​
Implementation Details

The GraphQL implementation uses:
  • Graphene - Python GraphQL library
  • MongoDB - Product data storage (see models/gql/schema.py:26)
  • Redis - Query result caching
  • Beaker - Cache region management
The GraphQL endpoint integrates with the cart middleware to apply exclusive pricing wrappers automatically.

Search API

Learn about the Dgraph-based search functionality

Product Catalog

REST API endpoints for products and categories

Build docs developers (and LLMs) love

Get started for freeTalk to us