Skip to main content

GraphQL API

ARC's primary product API is one code-first GraphQL schema at:

POST https://<arc-host>/graphql

The schema covers catalog, pricing, partners, sales, purchasing, inventory, documents, payments, analytics, settings, and surface-specific buyer operations.

Authentication boundary​

Most GraphQL resolvers require a user JWT:

Authorization: Bearer <arc-access-token>
Content-Type: application/json

The gm_live_… tenant API key is for the documented /api/service/* REST routes. It is not a general GraphQL credential. See Authentication for the full matrix.

Request shape​

Send a JSON object with query, optional variables, and an optional operationName:

{
  "operationName": "ListProducts",
  "query": "query ListProducts($limit: Int!) { products(limit: $limit) { items { id name } nextCursor hasNextPage } }",
  "variables": { "limit": 20 }
}

Use named operations and variables in production. Variables keep values out of query strings, make persisted operation tests possible, and produce clearer traces.

Query selection​

GraphQL returns only fields selected by the client. Start with the smallest projection that supports your use case:

query ListProducts($cursor: String, $filter: ProductFilterInput) {
  products(cursor: $cursor, limit: 20, filter: $filter) {
    items {
      id
      name
      sku
      status
      variants {
        id
        sku
        salePrice
        isActive
      }
    }
    nextCursor
    hasNextPage
  }
}

Prefer stable ids and explicit fields over broad selections. Store the schema snapshot used to generate your client types and run a schema-diff check when upgrading.

Mutations​

Mutations are permission-checked and frequently enforce document state, plan entitlements, stock, credit, tax method, idempotency, or document version. Read the operation description in the reference before calling it.

mutation ConvertQuote($quoteId: ID!, $idempotencyKey: String) {
  convertQuoteToSalesOrder(
    quoteId: $quoteId
    idempotencyKey: $idempotencyKey
  ) {
    id
    orderNumber
    status
    currency
    totalAmount
  }
}

Use a stable idempotency key when the mutation exposes one. If a mutation exposes expectedVersion, pass the version you read. Whether a stale version is refused depends on the server's concurrency mode: when enforcement is on you get a version conflict, so re-read the document and decide again; otherwise the write proceeds. Always re-read after writing.

Pagination​

There is no single pagination convention across every resolver. ARC's most common shapes are:

  • products: cursor, limit, nextCursor, hasNextPage, items;
  • invoices and payments: skip, take, total, and a list field;
  • some category, mobile, and hierarchy operations: nextCursor or pageInfo;
  • bounded lists: a plain array where the operation defines a limit.

The exact field signature and return type in the generated reference are authoritative. See Errors, pagination, and idempotency for client patterns.

Errors​

GraphQL may return HTTP 200 with an errors array. Treat the operation as failed or partial according to whether the affected data is present, and inspect errors[].extensions:

const response = await fetch(`${baseUrl}/graphql`, request);
const body = await response.json();

if (body.errors?.length) {
  for (const error of body.errors) {
    console.error(error.extensions?.code, error.extensions?.status, error.message);
  }
}

Switch on extensions.code first. Standard HTTP-style refusals arrive as BAD_REQUEST, UNAUTHENTICATED, FORBIDDEN, or BAD_USER_INPUT; any other HTTP status arrives as INTERNAL_SERVER_ERROR with the original status in extensions.status, so check that next. A few domain errors carry their own extensions.code (for example the cart conflict codes and IDEMPOTENCY_IN_PROGRESS). Others do not: a missing same-currency price arrives as INTERNAL_SERVER_ERROR, and the code appears only as the message prefix NO_PRICE_IN_CURRENCY:. Match that prefix rather than the rest of the sentence. See the error reference for the full list.

Introspection and the reference​

Introspection and the GraphQL playground are turned off in production, so do not build an integration that depends on them at runtime. Instead, download the public schema (SDL) that this site's reference is generated from — arc-public.graphql — and commit it to your project for code generation and query validation. Re-download it when the API changelog lists a change.

Open the generated GraphQL API reference →

The reference is exhaustive. The workflow guides explain which operations to use:

Subscriptions​

ARC also exposes GraphQL subscriptions over graphql-ws at the GraphQL endpoint. A connection supplies the JWT in connectionParams.authorization (or Authorization). Subscriptions are intended for authenticated application surfaces; they are not the recommended machine-to-machine change-feed contract. For server-to-server change notifications, use Webhooks. For quote-email notifications, see Events and webhooks.