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" }
  }
}

Looking up a record by an ID that does not exist returns null, not an error.

Queries

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

Mutations

A mutation returns the record it wrote, so you can select fields from it as you would in a query. Failures are reported in the top-level errors array with a code, as described in Errors; invalid input returns HTTP 400.

mutation {
  createWebhookEndpoint(
    input: {
      url: "https://example.com/redo-webhooks"
      topics: [PRODUCT_CREATED, PRODUCT_UPDATED]
    }
  ) {
    id
    secret
  }
}

Query cost & rate limits

The API uses query-cost rate limiting: each query’s cost is estimated from its shape before it runs and reserved against your store’s bucket, and the response reports the cost under extensions.cost. Requesting fewer results and fewer fields keeps cost, and latency, low. Mutations are not charged. 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

Reference

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