Skip to main content

​
Introduction

Openfront provides a powerful GraphQL API that gives you complete access to the platform’s e-commerce capabilities. The API is built on KeystoneJS 6 and provides a flexible, type-safe way to query and mutate your commerce data.

​
API Endpoint

The GraphQL API is available at: 
https://your-domain.com/api/graphql
For local development: 
http://localhost:3000/api/graphql

​
GraphQL Playground

Openfront includes an interactive GraphQL Playground for exploring the API during development. Access it at: 
http://localhost:3000/api/graphql
The GraphQL Playground is only available in development mode. In production, you’ll need to use a GraphQL client or tools like Postman, Insomnia, or Apollo Client.

​
Basic Query Structure

All GraphQL requests are sent as POST requests to the /api/graphql endpoint. Here’s a basic example:

​
Example: Fetching Products

query GetProducts {
  products(where: { status: { equals: "published" } }, take: 10) {
    id
    title
    handle
    thumbnail
    description {
      document
    }
    productVariants {
      id
      title
      sku
      prices {
        amount
        currency {
          code
        }
      }
    }
  }
}

​
Example: Creating a Cart

mutation CreateCart {
  updateActiveCart(
    cartId: "new"
    data: {
      email: "[email protected]"
      region: { connect: { id: "region_id_here" } }
    }
  ) {
    id
    email
    region {
      id
      name
      currency {
        code
      }
    }
  }
}

​
Using cURL

You can also interact with the API using cURL: 
curl -X POST https://your-domain.com/api/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -d '{
    "query": "query { products(take: 5) { id title handle } }"
  }'

​
Response Format

GraphQL responses follow a standard format: 
{
  "data": {
    "products": [
      {
        "id": "clx123456",
        "title": "Premium T-Shirt",
        "handle": "premium-t-shirt"
      }
    ]
  }
}

​
Error Handling

When errors occur, they’re returned in the errors array: 
{
  "errors": [
    {
      "message": "You do not have access to this resource",
      "path": ["products"],
      "extensions": {
        "code": "FORBIDDEN"
      }
    }
  ],
  "data": null
}

​
Key Features

​
Type Safety

The GraphQL API provides full type introspection. You can query the schema to discover available types, fields, and operations: 
query IntrospectionQuery {
  __schema {
    types {
      name
      kind
      description
    }
  }
}

​
Flexible Queries

Request only the fields you need, reducing payload size and improving performance: 
query MinimalProduct {
  products(take: 10) {
    id
    title
    # Only fetch what you need
  }
}

​
Filtering and Pagination

The API supports powerful filtering and pagination: 
query FilteredProducts {
  products(
    where: {
      status: { equals: "published" }
      title: { contains: "shirt", mode: insensitive }
    }
    take: 20
    skip: 0
    orderBy: { createdAt: desc }
  ) {
    id
    title
  }
}

​
Custom Mutations and Queries

Openfront extends the base KeystoneJS schema with custom operations for e-commerce workflows:

​
Cart Operations

  • activeCart - Get cart by ID
  • updateActiveCart - Update cart details
  • addDiscountToActiveCart - Apply discount codes
  • completeActiveCart - Convert cart to order

​
Order Operations

  • getCustomerOrder - Retrieve order details
  • getCustomerOrders - List customer orders

​
Analytics

  • getAnalytics - Fetch business analytics data

​
Shipping Operations

  • getRatesForOrder - Get shipping rates
  • validateShippingAddress - Validate addresses
  • trackShipment - Track shipment status

​
Invoice Operations (B2B)

  • createInvoiceFromLineItems - Generate invoices
  • payInvoice - Process invoice payments
  • getCustomerPaidInvoices - Retrieve payment history

​
Schema Documentation

For a complete list of available queries, mutations, and types, explore the GraphQL Playground’s documentation panel (accessible via the “Docs” button in the playground interface).

​
Next Steps

Authentication

Learn how to authenticate your API requests

Rate Limiting

Understand API rate limits and best practices

Build docs developers (and LLMs) love

Get started for freeTalk to us