Skip to main content

Client API Quick Start

Get started with the Client API in a few steps. This guide will walk you through registering a user, verifying email, authenticating, querying inventory, and adding items to a wantlist.

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

Prerequisites​

Before you begin, you'll need:

  • Store Domain: Your shop subdomain for the Client API URL (e.g. your-shop-name in https://your-shop-name.common-ground.io/graphql)
  • API Endpoint: https://your-shop-name.common-ground.io/graphql
  • Authentication Headers: as specified in Client API Overview

Both the email and password fields must be base64-encoded before sending to the server.

Step 1: Register a User​

Register a new customer account using the register mutation.

GraphQL Mutation:

mutation Register {
  register(
    email: "<base-64-encoded-email-address-string>"
    password: "<base64-encoded-password-string>"
    firstName: "First"
    lastName: "Last"
  ) {
    message
    user {
      _id
      id
      firstName
      lastName
      name
      email
      telephone
      taxNumber
      organisation
      isSubscribed
    }
    session {
      _id
      jwt
      expires
    }
  }
}

Response:

{
  "data": {
    "register": {
      "message": "An activation email was sent to ....",
      "user": {
        "_id": "693af48dbfbb51c94884e0a4",
        "id": null,
        "firstName": "First",
        "lastName": "Last",
        "name": null,
        "email": "test@example.com",
        "telephone": "",
        "taxNumber": "",
        "organisation": "",
        "isSubscribed": null
      },
      "session": null
    }
  }
}

Step 2: Verify Email​

Verify your email address using the link from the activation email.

Step 3: Login​

Authenticate using your verified customer email and password to obtain a JWT token. This requires a confirmed user account.

GraphQL Mutation:

mutation Login($email: String!, $password: String!) {
  login(email: $email, password: $password) {
    session {
      _id
      jwt
      expires
      user {
        _id
        email
        firstName
        lastName
      }
    }
    sessionsCount
  }
}

Variables:

{
  "email": "base64-encoded-email-address-string",
  "password": "base64-encoded-password-string"
}

Response:

{
  "data": {
    "login": {
      "session": {
        "_id": "693af50d643df000000e006e",
        "jwt": "eyJhbGciOiJI...",
        "expires": 1773247501000,
        "user": {
          "_id": "693af400000051c94884e0a4",
          "email": "buyer-email-address-here",
          "firstName": "First",
          "lastName": "Last"
        }
      },
      "sessionsCount": 1
    }
  }
}

Save the jwt value from the response - you'll need it for authenticated operations in Step 5.

Step 4: Query Inventory​

Query the store's inventory to browse available products. This is a public operation and the authentication of the current user is not mandatory.

Query:

query GetInventoryItems(
    $filters: InventoryFiltersInput!
    $pagination: PaginationInput!
) {
    inventoryItems(filters: $filters, pagination: $pagination) {
        items {
            _id
            id
            type
            uri
            data {
                title
                cat
                type
                manufacturer
                discogsId
                assetLink
                weight
                genres
                styles
                country
                releaseDate
                subtitle
                authors
                publisher
                publishedDate
                pageCount
                categories
                language
                format
            }
            listings {
                _id
                id
                available
                preOrder
                secondHand
                categories
                onePerCustomer
                comments
            }
        }
    }
}

Variables:

{
  "filters": {
    "stock": "inStock"
  },
  "pagination": { 
      "sort": "created", 
      "order": 1, 
      "page": 1,
      "limit": 5
    }
}

Response:

{
    "data": {
        "inventoryItems": {
            "items": [
                {
                    "_id": "693af000000fd932d1e62513",
                    "id": 12345,
                    "type": "ReleaseItem",
                    "uri": "https://www.my-vinyl-store.com/release/9987654321/various-the-unreleased-anthems",
                    "data": {
                        "title": "The Unreleased Anthems",
                        "cat": null,
                        "type": null,
                        "manufacturer": null,
                        "discogsId": 987654321,
                        "assetLink": null,
                        "weight": 230,
                        "genres": [
                            "Electronic"
                        ],
                        "styles": [
                            "Progressive House",
                            "Tribal",
                            "Progressive Trance",
                            "Tech House"
                        ],
                        "country": "UK",
                        "releaseDate": 911174400000,
                        "subtitle": null,
                        "authors": null,
                        "publisher": null,
                        "publishedDate": null,
                        "pageCount": null,
                        "categories": null,
                        "language": null,
                        "format": null
                    },
                    "listings": [
                        {
                            "_id": "693af2ab00004b5617334cd",
                            "id": 1765470890000,
                            "available": 1765470585000,
                            "preOrder": false,
                            "secondHand": true,
                            "categories": [],
                            "onePerCustomer": false
                        }
                    ]
                },
                // ... other entries
            ]
        }
    }
}

Save the data.inventoryItems.items[0].id (numeric item ID) from one of the items - you'll need it in Step 5.

What's happening:

  • The inventoryItems query fetches products from the store's public inventory
  • We're filtering for items that are in stock and paginating to get 5 items
  • This is a public query - no authentication required
  • Each item has listings (product variants) with stock and pricing information

Step 5: Add Item to Wantlist​

Add an item to the current user's wantlist using the item id from Step 4. This requires authentication, so use the JWT token from Step 3.

Mutation:

mutation AddToWantlist($id: Float!) {
  want(id: $id) {
    _id
    id
    type
    wanted
    data {
      title
    }
  }
}

Variables:

{
  "id": 12345
}

Response:

{
  "data": {
    "want": {
      "_id": "693af000000fd932d1e62513",
      "id": 12345,
      "type": "ReleaseItem",
      "wanted": true,
      "data": {
        "title": "The Unreleased Anthems"
      }
    }
  }
}

What's happening:

  • The want mutation adds or removes an item from your wantlist
  • If the item is already in your wantlist, calling this mutation again will remove it
  • The wanted field in the response indicates whether the item is currently in your wantlist
  • This mutation requires authentication (JWT token from Step 3)
  • The id must be the numeric item ID (not the _id)

Next Steps​