Getting started

This page takes you from zero to your first live response: create an API key, verify it, and run a query across your stores.

Before you begin

The API is available on the Advanced plan and above. If your account is on a lower plan, the diagnostic endpoint still works and will tell you the API is not enabled — see Authentication.
Only the account owner can create API keys.

Create an API key

In the EcomSolo platform, go to Settings → API keys and create a key. Assign it the read_data scope (required for every endpoint today). The secret — a string that starts with esk_live_ — is shown once, at creation. Copy it immediately and store it somewhere safe; it cannot be retrieved again.

warning

Treat the secret like a password. Use it only from server-side code, never in a browser or mobile app, and create one key per integration so you can revoke them individually.

Make your first request

Verify the key by calling GET /v1/account. Send the key as a bearer token in the Authorization header:

cURL
JavaScript
Python

curl https://api.ecomsolo.com/v1/account \
  -H "Authorization: Bearer esk_live_..."

const res = await fetch("https://api.ecomsolo.com/v1/account", {
  headers: { Authorization: "Bearer esk_live_..." },
});
const account = await res.json();
console.log(account);

import requests

res = requests.get(
    "https://api.ecomsolo.com/v1/account",
    headers={"Authorization": "Bearer esk_live_..."},
)
print(res.json())

A successful response looks like this:

{
  "account_id": "acct_9f3c...",
  "account_name": "Acme Retail Group",
  "subscription_id": "sub_2a71...",
  "api_enabled": true,
  "store_count": 3,
  "scopes": ["read_data"]
}

If api_enabled is false, your plan does not include the API yet — upgrade to Advanced or above. GET /v1/account is not plan-gated, so it always answers and is the right endpoint to diagnose a key.

Run your first query

Once the key is verified, post a SoloQL query to POST /v1/query. This one pulls consolidated sales, shipping, and order counts for every store over the last 30 days, broken out per store:

cURL
JavaScript
Python

curl https://api.ecomsolo.com/v1/query \
  -H "Authorization: Bearer esk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"query": "FROM sales SHOW total_sales, shipping, orders GROUP BY store SINCE -30d"}'

const res = await fetch("https://api.ecomsolo.com/v1/query", {
  method: "POST",
  headers: {
    Authorization: "Bearer esk_live_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: "FROM sales SHOW total_sales, shipping, orders GROUP BY store SINCE -30d",
  }),
});
console.log(await res.json());

import requests

res = requests.post(
    "https://api.ecomsolo.com/v1/query",
    headers={"Authorization": "Bearer esk_live_..."},
    json={"query": "FROM sales SHOW total_sales, shipping, orders GROUP BY store SINCE -30d"},
)
print(res.json())

The response is a columns and rows table, with the resolved currency and date window. See Querying with SoloQL for the full response shape and many more examples.

Tutorial: from a new key to your first query

Follow these steps end to end.

In the EcomSolo platform, open Settings → API keys (as the account owner) and create a key with the read_data scope.
Copy the esk_live_ secret shown at creation and store it securely — it is displayed only once and cannot be retrieved again.
Call GET /v1/account with the key in the Authorization: Bearer header and confirm you get a 200 with api_enabled set to true.
Post a SoloQL query such as FROM sales SHOW total_sales, orders GROUP BY store SINCE -30d to POST /v1/query and read back your consolidated, per-store results.

Next steps

Authentication — scopes, revocation, and security.
Querying with SoloQL — the query language in depth.
Datasets and fields — discover everything you can query.