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
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
}
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.
