Skip to main content

Admin API Quick Start

Get started with the Admin API in three simple steps. This guide will walk you through authenticating, querying inventory, and updating an item listing.

Prerequisites​

Before you begin, you'll need:

  • Access Keys: An access key and secret key from your admin panel
  • Store Domain or Config ID: The domain (e.g., www.my-store.com) or configuration ID for your store
  • API Endpoint: https://api.common-ground.io/graphql

See Developing for instructions on how to execute these operations using curl, Postman, Node.js, Python, or other tools.

Steps​

Step 1: Authenticate​

Authenticate using your access keys and the sessionLoginApi mutation to obtain a JWT token. This token will be used for all subsequent requests.

GraphQL Mutation:

mutation LoginAdminApi($accessKey: String!, $secretKey: String!) {
  sessionLoginApi(accessKey: $accessKey, secretKey: $secretKey) {
    _id
    jwt
    expires
    user {
      _id
      name
    }
  }
}

Variables:

{
  "accessKey": "your-access-key",
  "secretKey": "your-secret-key"
}

Response:

{
  "data": {
    "sessionLoginApi": {
      "_id": "693acbe4123c216a52a49c86e",
      "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "expires": 1765503707000,
      "user": {
        "_id": "69987a2cb4e0a5b5a92b23654",
        "name": "Admin User"
      },
    }
  }
}

Save the jwt value from the response - you'll need it for the next steps.

See Developing for instructions on how to execute this mutation using curl, Postman, Node.js, Python, or other tools.

Step 2: Query Inventory​

Query your inventory to retrieve the most recently created ReleaseItem entries and their listings.

Remember to include the Authorization: Bearer <JWT> and commonground-origin: <CONFIG_DOMAIN> headers.

GraphQL Query:

query GetInventory($inventoryFilters: InventoryFilters) {
    inventory(filters: $inventoryFilters) {
        entries {
            _id
            id
            type
            incId
            uniqueId
            oldId
            created
            modified
            isForbiddenForSale
            handle
            path
            uri
            listings {
                _id
                id
                status
            }
        }
    }
}

Variables:

{
  "inventoryFilters": {
    "page": 1,
    "limit": 10,
    "stock": "inStock",
    "itemTypes": ["ReleaseItem"],
    "status": "draft",
    "sort": "created",
    "order": -1
  }
}

Response:

{
    "data": {
        "inventory": {
            "entries": [
                {
                    "_id": "192ac95785a1c6e0f2cd0000",
                    "id": 12345678,
                    "type": "ReleaseItem",
                    "incId": 1234,
                    "uniqueId": "Nb-5lCuAuA",
                    "oldId": null,
                    "created": 1765464407276,
                    "modified": null,
                    "isForbiddenForSale": null,
                    "handle": null,
                    "path": "/release/12345678/my-release",
                    "uri": null,
                    "wants": null,
                    "listings": [
                        {
                            "_id": "191ad003253c206c52b5600d5",
                            "id": 1765465394324,
                            "status": "draft"
                        }
                    ]
                },
                // remaining entries
            ]
        }
    }
}

Save the data.inventory.entries[0].listings[0]._id from the response - you'll need it in Step 3.

What's happening:

  • The inventory query fetches items from your store's inventory
  • We're using inventory filters to tailor and sort the fetched results
  • The response includes the specified item details
  • Each item has a list of listings and we will use the listing _id of the first item in Step 3

Step 3: Update a Listing​

Update the listing's status using the listing ID from Step 2 and the itemListingUpdate mutation. This demonstrates how to modify data using mutations.

GraphQL Mutation:

mutation UpdateListing($listingRef: ID!, $input: ItemListingInput!) {
  itemListingUpdate(listingRef: $listingRef, itemListingInput: $input) {
    _id
    id
    modified
  }
}

Variables:

{
  "listingRef": "191ad003253c206c52b5600d5",
  "input": {
    "status": "published",
    "available": "2026-01-01"
  }
}

Response:

{
  "data": {
    "itemListingUpdate": {
      "_id": "191ad003253c206c52b5600d5",
      "id": 1765465394324,
      "modified": 1765464407276
    }
  }
}

What's happening:

  • The itemListingUpdate mutation modifies an existing listing
  • We're updating the status to "published" and setting the available date
  • The status and available fields are required when updating a listing
  • The mutation returns the updated item with the modified timestamp

Next Steps​