Skip to main content

Admin API Overview

The Admin API is a GraphQL API designed for backend operations and administrative tasks. Use it to manage your complete e-commerce infrastructure, including inventory, orders, configurations, users, and more.

Use Cases​

The Admin API is ideal for:

  • Inventory Management: Create, update, and manage your product catalog, items, listings, and stock levels
  • Order Processing: Handle orders, fulfillments, shipping, and order lifecycle management
  • Configuration Management: Configure store settings, payment methods, shipping policies, taxes, and integrations
  • User Management: Manage admin users, customers, permissions, and access control
  • Content Management: Organize collections, manage themes, and configure storefront settings
  • Analytics & Reporting: Access statistics, sales data, and business insights
  • Media Management: Upload and manage images, assets, and media files
  • Integration Management: Connect with external services like Discogs, Stripe, and other marketplaces

Best for: Backend services, administrative dashboards, inventory management systems, internal tools, and server-to-server integrations.

Endpoint​

The Admin API endpoint is:

  • https://api.common-ground.io/graphql/graphql

For administrative tasks related to uploading audio snippets use the following endpoint:

  • https://api.creators.common-ground.io/graphql

Authentication​

The Admin API authenticates requests using a secret key. You pass your secret key directly in the Authorization header as a Bearer token.

Secret Key​

Your secret key is created and managed in the admin panel of your Common Ground store.

Secret keys must be stored securely and never exposed in client-side code. Use them only for server-to-server communication.

Authentication Headers​

Include the following headers in all Admin API requests:

  • Authorization: Bearer <secret-key> - Your secret key
  • CommonGround-Origin: <config-id-or-domain> - The domain of your store on the Common Ground platform you're accessing (e.g. www.my-vinyl-store.com). This is either the custom domain configured in Common Ground or a sub-domain assigned by Common Ground.
Authorization: Bearer your-secret-key-here
CommonGround-Origin: www.my-vinyl-store.com

Rate Limits​

Admin API access is limited to 60 requests per minute.

Rate Limit 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

Implement exponential backoff when you receive 429 Too Many Requests responses. Cache responses when possible to reduce API calls, and batch operations when available to minimize request count.

Query Complexity​

While the Admin API doesn't enforce strict query complexity limits at this moment, consider the following:

  • Request Size: Request body size is limited to 20MB
  • Response Time: Complex queries with deep nesting may take longer to execute

Request only the fields you need, use pagination for large datasets, avoid deeply nested queries, and use filters to narrow down results.

Schema​

The Admin API uses a comprehensive GraphQL schema that includes:

  • Queries: Read operations for inventory, orders, users, configurations, and more
  • Mutations: Write operations for creating, updating, and deleting resources
  • Types: Rich type system for items, orders, users, configurations, and related entities
  • Input Types: Structured inputs for mutations and filters
  • Enums: Predefined sets of values for statuses, types, and categories

Download the Schema:

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

Download Admin API Schema

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

Next Steps​