Overview - Colossal

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.

​Endpoint

​When to use the API directly

​Available operations

​Making requests

​Mutation responses

​Error codes

Endpoint

When to use the API directly

Available operations

Making requests

Mutation responses

Error codes