# Commerce core concepts (https://developer.godaddy.com/en/docs/api-users/commerce/concepts)

***

title: Commerce core concepts
description: The entities, relationships, and access patterns behind the Commerce API.
related:
guides:

* title: "Manage a store"
  href: "/docs/api-users/commerce/set-up-a-store"
* title: "Manage catalog items"
  href: "/docs/api-users/commerce/manage-catalog"
* title: "Process an order"
  href: "/docs/api-users/commerce/manage-orders-and-customers"
* title: "Configure taxes"
  href: "/docs/api-users/commerce/configure-taxes"
  concepts:
* title: "About the Commerce API"
  href: "/docs/api-users/commerce"
* title: "How GoDaddy APIs work"
  href: "/docs/api-users/concepts/how-godaddy-apis-work"
  apis:
* title: "Commerce API scopes"
  href: "/docs/references/rest/commerce-scopes"

***

## 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](https://developer.godaddy.com/docs/api-users/commerce#your-stores) 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](https://developer.godaddy.com/docs/api-users/commerce/manage-catalog) 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](https://developer.godaddy.com/docs/api-users/commerce#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](https://developer.godaddy.com/docs/references/rest/commerce-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 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](https://developer.godaddy.com/docs/api-users/pagination) for the cross-cutting pagination reference.