Commerce core concepts
View as MarkdownThe entities, relationships, and access patterns behind the Commerce API.
Overview
The Commerce API spans a hierarchy of scoped entities, two transport patterns, and a scope model designed around the operation lifecycle rather than just read and write. This page explains the concepts you need before writing your first integration.
Store
Commerce revolves around one store. Everything belongs to a store. This includes:
- Catalog
- Orders
- Taxes
- Customers
- Channels
Every Commerce API call either targets a store directly or operates on a resource that belongs to one. Every call that reaches a store resource requires a storeId (a UUID that identifies the store). Your storeId is generated automatically when you create a GoDaddy Payments account. Sign in to your GoDaddy account and go to About the Commerce API to retrieve your storeId.
Entity model
The following diagram shows how Commerce entities relate to each other:
The following table describes the Commerce entities:
| Entity | Description |
|---|---|
| Store | The root container. All other entities belong to a store. |
| Catalog | SKUs and SKU groups that represent the products a store sells. |
| Tax | Tax rules and rates applied to orders at checkout. |
| Channel | The surface a customer buys from: an online store, a POS terminal, or a mobile app. |
| Customer | A person associated with one or more orders. |
| Order | A customer purchase. References both the customer and the catalog items bought. |
| Transaction | A payment record associated with an order. |
SKUs and SKU groups
The catalog domain models products as SKUs and SKU groups. There's no Product type in the Catalog GraphQL schema.
A SKU group is a collection of related SKUs (for example, a t-shirt available in multiple sizes). Each SKU represents one specific, purchasable variant. Creating a product in the Merchant Control Panel creates a SKU group with one or more child SKUs.
When working with the Catalog subgraph, you typically create a SKU group first, then create individual SKUs within it. Go to Manage catalog items for the full workflow.
Order lifecycle
Orders progress through a defined lifecycle. The scope model mirrors each stage. The following table lists the stages and the scopes required:
| Stage | Scope required |
|---|---|
| Read or query orders | commerce.order:read |
| Create a draft order | commerce.order:create |
| Update order fields | commerce.order:update |
| Complete (finalize) an order | commerce.order:complete |
| Cancel an order | commerce.order:cancel |
An order that's created as a draft must be explicitly completed. Cancelling stops the order.
REST and GraphQL subgraphs
Commerce uses two transport patterns depending on the complexity of the data. Categories with simple, predictable shapes (Store, Channel, Customer, Transaction) use REST. Categories with rich, nested relationships (Catalog, Orders, and Tax) expose a GraphQL subgraph, which lets you fetch related data in a single round trip and select exactly the fields you need.
GraphQL subgraphs also require an x-store-id header (in addition to or instead of the path {storeId}, depending on the subgraph). Go to the REST vs GraphQL subgraph table on About the Commerce API for exact endpoints, path parameters, and header rules per subgraph.
Scope model
Commerce scopes follow the pattern commerce.{resource}:{action}. Request the least privilege your integration needs. Each how-to page lists the scopes required for each operation. Go to Commerce API scopes for the complete scope-to-endpoint mapping.
Order scopes
The Order resource has the most granular scope model, with a separate scope for each lifecycle transition:
| Scope | What it grants |
|---|---|
commerce.order:read | Query orders and line items |
commerce.order:create | Create draft orders |
commerce.order:update | Update order fields |
commerce.order:complete | Mark an order complete |
commerce.order:cancel | Cancel an order |
This design lets you grant an integration exactly the access it needs. A reporting tool might only need commerce.order:read; an order-management app needs read and complete.
Catalog scope naming
Catalog scopes naming conventions
Catalog scopes are named commerce.product:* for historical reasons, even though the GraphQL schema uses SKU and SKU group terminology. Request commerce.product:read to query catalog data — not a sku or catalog variant.
Cursor-based pagination
The GraphQL subgraphs (Catalog, Order, Tax) use cursor-based pagination on connection types. Paginated queries return a connection object with a nodes or edges array and a pageInfo object.
| Argument | Description |
|---|---|
first | Return the first N results after the cursor |
after | Cursor from the previous page's pageInfo.endCursor |
last | Return the last N results before the cursor |
before | Cursor from the previous page's pageInfo.startCursor |
Connection types also expose totalCount so you can display progress or calculate how many pages remain.
REST endpoints use offset-based or token-based pagination depending on the resource. Go to Paginate results for the cross-cutting pagination reference.
Related
Last updated on
How is this guide?