AlmondTill/G3N API

On this page

AlmondTill/G3N API

One API for everything in your business — the same operations your Office, your registers and your storefront use, open to your own code and to the tools you connect. This is its reference: what every operation means and does, in plain words, with a request and a response you can copy.

What you need

Your first call

Five minutes, three steps. Every call is a POST to https://api.almondtill.com/ with a JSON body of query, variables and extensions. A change names the API version it was written against under extensions.at.version; a read may leave it out.

Step 1 — mint a key

An owner of your organization group mints an API key in the office, under API keys, choosing exactly what the key may do — or does the same from their own code with mintApiKey. The secret is shown once: copy it into your integration's secret store then and there.

Step 2 — exchange the secret for a session

No token yet — the secret is the credential. Call exchangeApiKey naming the organization the session will act in:

{
  "query": "mutation ExampleExchangeApiKey($input: ExchangeApiKeyInput!) {\n  exchangeApiKey(input: $input) {\n    token\n    expiresAt\n  }\n}",
  "variables": {
    "input": {
      "secret": "<your key secret>",
      "orgId": "01900000-0000-7000-8000-b0cf4f3c0000"
    }
  },
  "extensions": {
    "at": {
      "version": {
        "name": "genesis",
        "number": 0
      }
    }
  }
}

The answer carries the session token and the moment it expires (24 hours on; use does not extend it):

{
  "data": {
    "exchangeApiKey": {
      "token": "<your session token>",
      "expiresAt": "2027-01-31T00:00:00.000Z"
    }
  },
  "extensions": {
    "at": {
      "callId": "01EXAMPLE-CALL-ID",
      "version": {
        "requested": {
          "name": "genesis",
          "number": 0
        },
        "serviced": {
          "name": "genesis",
          "number": 0
        }
      }
    }
  }
}

Step 3 — read your first page

Send it with the token as authorization: Bearer <your session token>:

{
  "query": "query FirstBrands($limit: Int) { brands(limit: $limit) { items { sysId caption status } nextToken } }",
  "variables": {
    "limit": 3
  }
}

The answer is a page:

{
  "data": {
    "brands": {
      "items": [
        {
          "sysId": "BR-EXMP-0000-000F",
          "caption": "Blue jeans",
          "status": "active"
        }
      ],
      "nextToken": null
    }
  },
  "extensions": {
    "at": {
      "callId": "01EXAMPLE-CALL-ID",
      "version": {
        "requested": null,
        "serviced": {
          "name": "genesis",
          "number": 0
        }
      }
    }
  }
}

Every answer carries extensions.at — the call id to quote when something needs a look, the version that served you, and the stat of the call. Every id in the examples is made up and resolves nowhere.

The map