Skip to main content

Admin API Quick Start

Get started with the Admin API in two simple steps. This guide will walk you through querying inventory and updating an item listing. An optional step is included for creating a release item if you don't have one yet.

Prerequisites​

Before you begin, you'll need:

  • Secret Key: A secret key from your admin panel (created and managed in Common Ground)
  • Store Domain or Config ID: The domain (e.g., www.my-store.com) or configuration ID for your store
  • Admin API Endpoint: as specified in Admin API Overview
  • Authentication Headers: as specified in Admin API Overview

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

Optional: Create a Release Item​

If you don't have any items in your inventory yet, you can create a release item using the itemCreate mutation. This step is optional - you can skip it if you already have items in your inventory.

GraphQL Mutation:

mutation ItemCreate(
  $type: String!
  $descriptions: ItemInputDescriptions
  $itemCreateReleaseInput: ItemReleaseInput
  $listings: [ItemListingInput]
  $method: String
) {
  itemCreate(
    type: $type
    descriptions: $descriptions
    itemCreateReleaseInput: $itemCreateReleaseInput
    listings: $listings
    method: $method
  ) {
    _id
    id
    type
    path
    uri
  }
}

Variables:

{
  "type": "ReleaseItem",
  "descriptions": {
    "short": "A classic electronic release from the 1990s",
    "long": "This release features groundbreaking electronic music that defined the era. Includes multiple tracks showcasing innovative production techniques."
  },
  "itemCreateReleaseInput": {
    "title": "Electronic Journey",
    "releaseDate": 794678400000,
    "weight": 250,
    "genres": ["Electronic"],
    "styles": ["Techno", "House"],
    "formats": [
      {
        "name": "12\"",
        "qty": 1,
        "text": "",
        "descriptions": []
      },
      {
        "name": "Vinyl",
        "qty": 1,
        "text": "",
        "descriptions": []
      }
    ],
    "tracklist": [
      {
        "position": "A1",
        "title": "Track One",
        "duration": "6:30",
        "type_": "track",
        "artists": []
      },
      {
        "position": "A2",
        "title": "Track Two",
        "duration": "5:45",
        "type_": "track",
        "artists": []
      },
      {
        "position": "B1",
        "title": "Track Three",
        "duration": "7:15",
        "type_": "track",
        "artists": []
      }
    ],
    "artists": [
      {
        "name": "Artist Name",
        "role": "Main"
      }
    ],
    "labels": [
      {
        "name": "Label Name",
        "catno": "CAT-001"
      }
    ]
  },
  "listings": [
    {
      "stock": {
        "quantity": 10
      },
      "status": "private",
      "available": "2024-01-15T00:00:00.000Z",
      "location": "",
      "secondHand": false,
      "taxDefinition": "VAT",
      "categories": [],
      "comments": "",
      "privateComments": "",
      "onePerCustomer": false,
      "supplierCode": "SUPPLIER-001",
      "preventDiscogsListing": null,
      "preOrder": false,
      "prices": {
        "sale": 25.99,
        "cost": 15.00
      },
      "options": [
        {
          "name": "Media Condition",
          "value": "Mint (M)"
        },
        {
          "name": "Sleeve Condition",
          "value": "Mint (M)"
        }
      ],
      "barcode": "1234567890123",
      "sku": "CAT-001"
    }
  ]
}

Response:

{
  "data": {
    "itemCreate": {
      "_id": "192ac95785a1c6e0f2cd0000",
      "id": 12345678,
      "type": "ReleaseItem",
      "path": "/release/12345678/electronic-journey",
      "uri": "https://www.example.com/release/12345678/electronic-journey"
    }
  }
}

Save the _id from the response - you can use it to query or update the item later.

What's happening:

  • The itemCreate mutation creates a new release item in your inventory
  • The itemCreateReleaseInput contains release-specific information (title, releaseDate, genres, tracklist, artists, labels)
  • The releaseDate must be a timestamp in milliseconds (e.g., 794678400000 for January 1, 1995) or an ISO date string
  • Each track in the tracklist requires position, title, duration, type_ (e.g., "track"), and artists (can be an empty array)
  • The formats array requires objects with name, qty, text, and descriptions fields
  • The listings array defines the initial listing with stock, pricing, and condition information
  • The method parameter is optional and used for Discogs imports; it can be omitted for manual API creation
  • The mutation returns the created item with its _id, id, path, and uri

Steps​

Step 1: Query Inventory​

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

Query:

query GetInventory($inventoryFilters: InventoryFilters) {
    inventory(filters: $inventoryFilters) {
        entries {
            _id
            id
            type
            incId
            uniqueId
            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",
                    "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 2.

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 2

Step 2: Update a Listing​

Update the listing's status using the listing ID from Step 1 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": 1767293273000
  }
}

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​