Skip to main content

Client API Quick Start

Get started with the Client API in a few steps. This guide will walk you through authenticating as a customer, querying inventory, and creating a checkout.

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:

  • Customer Account: An email and password for a registered customer account
  • Store Domain: The domain of the store you're accessing (e.g., www.my-store.com)
  • API Endpoint: https://api-client.common-ground.io/graphql

If you don't have a customer account, you can register one using the register mutation.

Step 1: Authenticate as a Customer​

Authenticate using your customer email and password to obtain a JWT token. This token will be used for authenticated operations.

Remember to include the ommonground-origin: <CONFIG_DOMAIN> header.

Both the email and password fields must be base64-encoded before sending to the server. The same applies to the register mutation.

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 3.

Step 2: Query Inventory​

Now query the store's inventory to browse available products. This is a public operation and doesn't require authentication.

GraphQL 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].listings[0].id (numeric listing ID) from one of the items - you'll need it in Step 4.

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 so you can also allow unauthenticated users
  • Each item has listings (product variants) with stock and pricing information

Step 3: Create a Checkout​

Create an empty checkout object. This requires authentication, so use the JWT token from Step 1.

The checkoutCreate mutation doesn't accept any parameters - it creates an empty checkout. You'll add items in the next step.

GraphQL Mutation:

mutation CheckoutCreate {
    checkoutCreate {
        _id
        id
        configRef
        origin
        created
        orderId
        updated
        expires
        status
        message
        useSingleAddress
    }
}

Variables:

{}

Response:

{
    "data": {
        "checkoutCreate": {
            "_id": "693afb015dc249f21ccba766",
            "id": "abc-AbC1d",
            "configRef": "0f00d000d0000c0001111e00",
            "origin": "Online",
            "created": 1765473025596,
            "orderId": null,
            "updated": 1765473025596,
            "expires": 1768151425596,
            "status": "open",
            "message": null,
            "useSingleAddress": true
        }
    }
}

Save the id value from the response - you'll need it in Step 4 to add items.

What's happening:

  • The checkoutCreate mutation creates a new empty shopping cart (checkout)
  • This mutation requires authentication (JWT token from Step 1)
  • The response includes the checkout id which you'll use to add items
  • The checkout starts with status: "open" and no items

Step 4: Add Items to Checkout​

Now add items to the checkout using the checkout id from Step 3 and the listing id from Step 2.

GraphQL Mutation:

mutation CheckoutUpdateItems($id: String!, $items: [CheckoutItemInput!]) {
  checkoutUpdateItems(id: $id, items: $items) {
    _id
    id
    configRef
    origin
    created
    updated
    expires
    status
    message
    useSingleAddress
  }
}

Variables:

{
  "id": "abc-AbC1d",
  "items": [
    {
      "listingId": 1765470890000,
      "quantity": 1
    }
  ]
}

Response:

{
  "data": {
    "checkoutUpdateItems": {
      "_id": "693afb015dc249f21ccba766",
      "id": "abc-AbC1d",
      "configRef": "0f00d000d0000c0001111e00",
      "origin": "Online",
      "created": 1765473025596,
      "updated": 1765475982226,
      "expires": 1768154382226,
      "status": "open",
      "message": null,
      "useSingleAddress": true
    }
  }
}

What's happening:

  • The checkoutUpdateItems mutation adds items to an existing checkout
  • We're using the checkout id from Step 3 and the listing id from Step 2
  • The listingId must be the numeric id field from the listing (not the _id)
  • This mutation requires authentication (JWT token from Step 1)
  • The response shows the updated checkout with the new items

Next Steps​