Getting Started

This guide walks you through connecting to the Endless Commerce GraphQL API, authenticating your requests, and making your first queries. By the end you will be able to retrieve live data from your account.

GraphQL Endpoint

All API requests are sent as HTTP POST to a single endpoint:

https://api.endlesscommerce.com/graphql

https://api-sandbox.endlesscommerce.com/graphql

Every request must include at minimum the Content-Type header:

Content-Type: application/json

Authentication

The API supports two authentication methods. Use whichever one applies to your account.

Option A - API Key (recommended for integrations)

If you have been provided an API access token (it starts with cat_), include it in the X-EC-Access-Token header. No sign-in step is required.

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-EC-Access-Token: YOUR_ACCESS_TOKEN" \
  -H "X-Company-Id: YOUR_COMPANY_ID" \
  --data '{ "query": "{ __typename }" }' \
  https://api.endlesscommerce.com/graphql

Replace YOUR_ACCESS_TOKEN with the token you were given and YOUR_COMPANY_ID with your company's Endless ID or handle.

Option B - User Session (email & password)

Use the signIn mutation to obtain a short-lived bearer token.

Step 1 - Sign in

curl -X POST \
  -H "Content-Type: application/json" \
  --data '{
    "query": "mutation { signIn(input: { loginIdentifier: \"your@email\", password: \"your-password\" }) { token tokenExpiration } }"
  }' \
  https://api.endlesscommerce.com/graphql

A successful response returns the token and its expiration time:

{
  "data": {
    "signIn": {
      "token": "a]1b2c3d4e5f6...",
      "tokenExpiration": "2026-03-25T13:00:00Z"
    }
  }
}

Step 2 - Use the token

Include the token in the Authorization header on all subsequent requests:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  --data '{ "query": "{ me { id email firstName lastName } }" }' \
  https://api-dev.endlesscommerce.com/graphql

Session tokens expire after a period of inactivity (default 1 hour). When a token expires, sign in again to obtain a new one.

Request Headers

Header	Required	Description
Content-Type: application/json	Always	Must be set on every request.
X-EC-Access-Token	For API key auth	Your API access token (starts with cat_).
Authorization: Bearer <token>	For session auth	The token returned by the signIn mutation.
X-Company-Id	Recommended	Your company UUID or handle. Required by most queries.
X-Brand-Id	Optional	A brand UUID or handle to scope results to a single brand.

Note: When authenticating with an API key you do not need the Authorization header, and vice versa.

Your First Query

Once authenticated, try a simple query to verify everything is working. The example below uses API key authentication:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-EC-Access-Token: YOUR_ACCESS_TOKEN" \
  -H "X-Company-Id: YOUR_COMPANY_ID" \
  --data '{
    "query": "{ listInventory(first: 5) { nodes { id } } }"
  }' \
  https://api-dev.endlesscommerce.com/graphql

Using Variables

For queries with parameters, pass variables as a separate JSON object rather than interpolating values into the query string:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-EC-Access-Token: YOUR_ACCESS_TOKEN" \
  -H "X-Company-Id: YOUR_COMPANY_ID" \
  --data '{
    "query": "query GetProduct($id: ID!) { product(id: $id) { id name sku status } }",
    "variables": { "id": "your-product-id" }
  }' \
  https://api-dev.endlesscommerce.com/graphql

Pagination

List queries use cursor-based pagination. Request the pageInfo object to navigate through results:

query {
  listInventory(first: 25, after: "cursor_value") {
    nodes {
      id
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Pass the endCursor value as the after argument in the next request to retrieve the following page.

Response Format

Successful Response

A successful response returns HTTP status 200 with a data field containing the requested information:

{
  "data": {
    "listInventory": {
      "nodes": [
        { "id": "abc-123" },
        { "id": "def-456" }
      ]
    }
  }
}

Error Response

When an error occurs the response includes an errors array with details about what went wrong:

{
  "data": null,
  "errors": [
    {
      "message": "A descriptive error message",
      "locations": [{ "line": 1, "column": 3 }],
      "path": ["listInventory"],
      "extensions": {
        "code": "E0004",
        "name": "RestrictedAccess",
        "status": 401
      }
    }
  ]
}

Always check for the presence of the errors field when processing API responses.

Common Errors

Error	Cause	Solution
You must be logged in to access this resource	Missing or invalid authentication header.	Verify your X-EC-Access-Token or Authorization header.
Company context is required	No company specified.	Add the X-Company-Id header to your request.
Not authorized to perform this action	Your account lacks the required permission.	Contact Endless Commerce support to request access.
Cannot return null for non-nullable field	The query requires a context your auth method does not provide (e.g. me with an API key).	Use a different query appropriate for your auth method.

Exploring the Schema

Use any of these tools to discover available queries, mutations, and types:

• GraphiQL - Interactive in-browser IDE available for all compannies by adding /graphiql to the url. E.g. https://app.endlesscommerce.com/company-handle/graphiql.
• Introspection query - Send { __schema { queryType { fields { name description } } } } to list all top-level queries.

Need Help?

If you have questions or run into issues, reach out to support@endlesscommerce.com and we'll be happy to assist.