Overview

The Storefront API. A public GraphQL endpoint for products, cart, checkout, and orders.

The Storefront API is a public GraphQL endpoint for building commerce experiences. It powers the Storefront SDK under the hood, but you can also query it directly with any GraphQL client.

Endpoint

POST https://api.colossal.sh/api/v1/graphql

Authenticated with a storefront API key. Safe to call from the browser.

When to use the API directly

Most developers use the Storefront SDK (React hooks). Use the raw GraphQL API when:

• You’re not building with React
• You need server-side data fetching
• You want full control over queries and caching

Available operations

Area	Queries	Mutations
Products	Browse products, variants, pricing, and media
Cart	Fetch cart with line items	Create cart, add/update/remove items
Checkout	Get checkout session details	Create, update, and complete checkout
Orders	View order details
Store	Fetch store config by UID, slug, or domain
Customers		Create customer records

Making requests

import { GraphQLClient } from "graphql-request";

const client = new GraphQLClient("https://api.colossal.sh/api/v1/graphql", {
  headers: {
    Authorization: `Bearer ${STOREFRONT_API_KEY}`,
  },
});

const data = await client.request(query, variables);

Mutation responses

All mutations return a consistent result type:

{
  success: Boolean!
  data: Entity
  message: String
  error_code: String
  field: String
}

Check success before using data. If success is false, inspect error_code and message for details.

Error codes

Code	Description
NOT_FOUND	Resource doesn’t exist
VALIDATION_ERROR	Invalid input data
INTERNAL_ERROR	Server error

An Admin API with full read/write access for server-side operations is coming soon.