Queries & mutations

Every v3 request is a single POST carrying a GraphQL document. Queries read data; mutations write it.

Sending an operation

The request body is JSON with a query field and optional variables and operationName:

{
  "query": "query GetProduct($id: ID!) { product(id: $id) { id title sku } }",
  "variables": { "id": "prd_123" }
}

The response mirrors the shape you asked for, under data:

{
  "data": {
    "product": { "id": "prd_123", "title": "Wool Runner", "sku": "WR-9" }
  }
}

Queries

query {
  productFamilies(first: 5) {
    nodes {
      id
      title
      products(first: 3) {
        nodes {
          id
          sku
          price {
            amount
            currency
          }
        }
      }
    }
  }
}

Mutations

mutation {
  upsertWebhookEndpoint(
    input: {
      url: "https://example.com/redo-webhooks"
      topics: [product_created, product_updated]
    }
  ) {
    id
    created
    secret
  }
}

Query cost & rate limits

The API uses query-cost rate limiting: each request’s cost is estimated from the shape of the query before it runs and reserved against your account’s bucket, and every response reports the cost under extensions.cost. Requesting fewer results and fewer fields keeps cost — and latency — low. See Rate limiting for the cost model, throttleStatus, and how to handle 429 / THROTTLED responses.

Rate limiting — query cost and throttling
Pagination — paging through connections
Errors — error shapes and codes

Getting Started

Access

Queries & mutations

Sending an operation

Queries

Mutations

Query cost & rate limits

​Sending an operation

​Queries

​Mutations

​Query cost & rate limits

​Related

Sending an operation

Queries

Mutations

Query cost & rate limits

Related