Skip to main content

Client API Overview

The Client API is a GraphQL API optimized for frontend applications and customer-facing integrations. Use it to build e-commerce storefronts, mobile applications, and public websites that interact with your Common Ground store.

Use Cases​

You can use the Client API for:

  • Product Catalog: Display products, browse inventory, search items, and showcase collections
  • Customer Accounts: User registration, login, profile management, and preferences
  • Shopping Experience: Browse products, view details, manage wantlists, and access suggestions
  • Checkout & Orders: Create checkouts, process payments, view order history, and track orders
  • Search & Discovery: Search products, filter inventory, browse by artists/labels, and get recommendations

Best for: E-commerce storefronts, mobile applications, public websites, customer-facing integrations, and frontend applications.

Endpoint​

The Client API is available at:

  • Client API: POST https://your-shop-name.common-ground.io/graphql

Authentication​

The Client API uses customer (buyer) authentication for protected operations.

Many operations are public and don't require authentication. Only user-specific operations (orders, profile, wantlist) require authentication of the current user.

Customer Authentication​

Sign-in the customer before using customer-facing features like viewing orders, managing profiles, and accessing wantlists.

Using Authentication Tokens​

After obtaining an authentication token from the login operation, include it in authenticated requests:

  • Authorization: Bearer <jwt> - The customer session JWT (for authenticated operations)

The store is selected by the subdomain in the endpoint URL (your-shop-name.common-ground.io). You do not need a CommonGround-Origin header when calling that URL.

Rate Limits​

Client API rate limits are applied per IP and may vary depending on environment and caller type.

  • In production: browsers are allowed a higher request budget than server-to-server integrations.
  • In non-production: limits are significantly higher.

Rate Limit Response Headers​

The API returns rate limit information in response headers:

  • RateLimit-Limit - Maximum requests allowed in the window
  • RateLimit-Remaining - Remaining requests in the current window
  • RateLimit-Reset - Time when the rate limit window resets

Best Practices​

  • Implement exponential backoff when you receive 429 Too Many Requests responses
  • Cache public data (inventory, collections, config) to reduce API calls
  • Use pagination for large datasets
  • Consider using inventory dumps for bulk data access

Query Complexity​

Keep operations shallow and close to the examples in these docs:

  • Prefer 3–4 levels of nesting (for example root field → object → nested fields). Deeper nesting is rarely needed for Client workflows
  • Request only the fields you need
  • Use pagination for inventory and collections
  • Use filters to narrow results
  • Cache public data when appropriate

Follow the query and mutation examples throughout the Client API documentation—they reflect the nesting depth and field selection patterns that work well in production.

Schema​

The Client API uses a comprehensive GraphQL schema optimized for frontend use:

  • Queries: Read operations for inventory, items, collections, orders, users, and more
  • Mutations: Write operations for login, registration, checkout, orders, and user management
  • Types: Rich type system for items, orders, users, checkouts, collections, and related entities
  • Input Types: Structured inputs for mutations, filters, and pagination
  • Enums: Predefined sets of values for statuses, types, and categories

You can download the complete Client API schema file for use with GraphQL tools, code generators, and IDEs:

Download Client API Schema

Schema introspection from the GraphQL endpoint is disabled. Use the downloadable schema file instead.

Next Steps​