# Orders GraphQL (https://developer.godaddy.com/en/docs/references/rest/orders)

***

title: Orders GraphQL
description: Query and mutate the commerce order subgraph.
full: true
----------

Commerce order GraphQL over HTTP. Use `commerce.order:read` to query; mutations
require one of `commerce.order:create`, `:update`, `:cancel`, or `:complete`.
See [Commerce API Scopes](https://developer.godaddy.com/docs/references/rest/commerce-scopes).

**Endpoint:** `POST /v1/commerce/order-subgraph`

Select the store with a required `x-store-id` header — there is no `{storeId}`
path segment on this endpoint. Mutations that take an input object also include a
required `context.storeId`; `id`-only mutations (e.g. `cancelOrder`) rely on the
header alone.

Order and line-item IDs are opaque global IDs shaped like `Order_<KSUID>` and
`LineItem_<KSUID>` (e.g. `Order_2N8x…`) — not numeric or base64-encoded. Pass the
full value verbatim wherever an `id` or `orderId` argument appears.

Sidebar is grouped by **action/resource**. Expand a resource, then **Query**
(`commerce.order:read`, 6 fields) or **Mutation**
(15 fields).

## Example query

query

Requires `commerce.order:read`. See [`orderById`](https://developer.godaddy.com/docs/references/rest/orders/order/queries/orderById) for the full schema.

```graphql
query GetOrder($id: ID!) {
  orderById(id: $id) {
    id
    number
    statuses { status }
  }
}
```

```bash
curl -X POST "https://api.godaddy.com/v1/commerce/order-subgraph" \
  -H "Authorization: Bearer $GODADDY_PAT" \
  -H "Content-Type: application/json" \
  -H "x-store-id: $STORE_ID" \
  -d '{
    "query": "query GetOrder($id: ID!) { orderById(id: $id) { id number statuses { status } } }",
    "variables": { "id": "ORDER_ID" }
  }'
```

## Example mutation

mutation

Requires the scope matching the operation (e.g. `commerce.order:cancel`). See [`addOrder`](https://developer.godaddy.com/docs/references/rest/orders/order/mutations/addOrder) for the full schema.

```graphql
mutation CancelOrder($id: ID!, $force: Boolean) {
  cancelOrder(id: $id, force: $force) {
    id
    statuses { status }
  }
}
```

## Error handling

This is a GraphQL endpoint, so **most failures still return HTTP 200**. Resolver
and authorization errors are reported inside the `errors` array — inspect
`errors[].extensions.code` rather than keying off the HTTP status. Only malformed
GraphQL documents fail at the transport layer with HTTP 400.

| `extensions.code`           | HTTP | When                                                                                                              |
| --------------------------- | ---- | ----------------------------------------------------------------------------------------------------------------- |
| `UNAUTHENTICATED`           | 200  | A store-scoped operation was called without a valid `x-store-id` header.                                          |
| `INTERNAL_SERVER_ERROR`     | 200  | The `x-store-id` header is present but is invalid or not a store you can access (a masked authorization failure). |
| `GRAPHQL_VALIDATION_FAILED` | 400  | The query references an unknown field or is otherwise not valid against the schema.                               |

```json
{
  "data": null,
  "errors": [
    {
      "message": "Unauthorized",
      "extensions": { "code": "UNAUTHENTICATED" }
    }
  ]
}
```

***

## HTTP reference

OpenAPI contract for the subgraph POST (headers, auth, response envelope):

## POST /v1/commerce/order-subgraph

Order GraphQL endpoint

Proxies GraphQL to the order subgraph. Use the `query` field for the GraphQL document and optional `variables` / `operationName`.

### Header parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `x-store-id` | string | yes | ID of the store the operation targets — send it on every request. Required for all order queries and mutations; omitting it returns HTTP 200 with a GraphQL error whose `extensions.code` is `UNAUTHENTICATED`. (Schema-level metadata requests such as `__typename` and introspection are the only operations that resolve without it.) |

### Request body (required)

Content-Type: `application/json`

```json
{
  "query": "query GetOrder($id: ID!) { orderById(id: $id) { id number statuses { status } } }",
  "variables": {
    "id": "ORDER_ID"
  }
}
```

Schema:

- object
  - `query` (required): string
  - `variables`: object
  - `operationName`: string

### Responses

**200** — GraphQL response

Content-Type: `application/json`

Schema:

- object
  - `data`: object
  - `errors`: array
      - items:

**400** — Invalid request

**401** — Unauthorized

**403** — Forbidden

**500** — Internal server error

**Security:** requires `PAT`; scopes `commerce.order:read`, `commerce.order:create`, `commerce.order:update`, `commerce.order:cancel`, `commerce.order:complete`, `commerce.order:archive`.