About the Commerce API
View as MarkdownBuild integrations to manage stores, catalogs, orders, customers, and fulfillment with GoDaddy Commerce.
Overview
Use the Commerce API to manage stores, catalogs, orders, customers, and taxes.
This page covers what you need to build a Commerce integration (any software that reads or updates a store's data through the Commerce API). Every request targets one store, identified by its storeId.
Before you start
The following table lists the items you need to use the Commerce API on your own store:
| Item | Description | Note |
|---|---|---|
| GoDaddy Payments account | A separate account from your standard GoDaddy account that creates your commerce store and the storeId you'll pass to every Commerce API call. | Go to GoDaddy Payments for an overview of what's included and Get started with GoDaddy Payments to create your account and activate your store. |
| Personal Access Token (PAT) | A token you use to authenticate your API calls. | Go to Authenticate to create a PAT with the scopes your integration needs. |
| Store ID | A unique identifier for your commerce store. | Sign in and go to the Your stores section to see your store IDs. |
GoDaddy Payments account
GoDaddy Payments is a separate account from your standard GoDaddy account. When you create a GoDaddy Payments account, GoDaddy creates a business and a default store for you and generates the store's storeId. There's no API to create a GoDaddy Payments account or a store, so set up your account through the GoDaddy Payments UI.
Go to GoDaddy Payments for an overview of what's included and Get started with GoDaddy Payments to create your account.
Your stores
Your stores include a storeId that you'll pass to every Commerce API call. You must sign in to see your store IDs. When you sign in, information about your stores, including your storeIds, displays in this section.
How the API is structured
The store is the root resource. Your catalog, taxes, and channels all belong to a specific store, and most endpoints take a {storeId} path parameter.
For the data model, scope model, and deeper access patterns, go to Commerce core concepts.
REST vs GraphQL subgraph
Three categories expose a single GraphQL endpoint that accepts queries and mutations. Use schema introspection to discover available types and operations. The following table shows the different categories and the endpoints they expose:
| Category | Endpoint | storeId requirement |
|---|---|---|
| Catalog | POST /v2/commerce/stores/{storeId}/catalog-subgraph | Send the same store ID in the path {storeId} and the x-store-id header. You must send the header. If they differ, the subgraph uses the header. |
| Order | POST /v1/commerce/order-subgraph | Required x-store-id header selects the store; there's no {storeId} path parameter. Mutations that take an input object also require context.storeId; id-only mutations (e.g. cancelOrder) rely on the header. |
| Tax | POST /v2/commerce/stores/{storeId}/tax-subgraph | Path parameter and x-store-id header (must match). |
The remaining categories (Channel, Customer, Store, and Transaction) use standard REST endpoints.
Use:
- REST for straightforward reads and writes on a single resource. It's the shortest path and needs no query.
- GraphQL subgraph on catalog, orders, and tax when you need related data in one round trip or want to select exactly the fields you use. The shapes are richer and vary more, so fetching precisely is worth it.
Most REST endpoints use v1; the exception is Transaction, which uses v2 (/v2/commerce/stores/{storeId}/transactions). Each GraphQL endpoint path in the preceding table includes its version.
Build your integration
The following table lists the guides in the order you typically build a Commerce integration:
| Step | Guide | What you do |
|---|---|---|
| 1 | Set up a store | Read store settings and business details, and list sales channels |
| 2 | Manage your catalog | Create and manage products |
| 3 | Manage orders and customers | Process orders, transactions, and customer records |
| 4 | Configure taxes | Set up tax rates |
API categories
The following table shows the different categories, the tasks they support, and their transport:
| Category | Task | Transport | Guide |
|---|---|---|---|
| Store | Retrieve your store ID | REST | Your stores |
| Channel | List sales channels | REST | List sales channels |
| Catalog | Create and manage SKUs | GraphQL | Manage catalog items |
| Order | Create and track orders | GraphQL | Process an order |
| Customer | Create and manage customers | REST | Manage a customer |
| Transaction | View payment transactions | REST | View transactions |
| Tax | Configure tax rates | GraphQL | Configure taxes |
Platform conventions
Commerce uses the same conventions as every GoDaddy API, so you learn them once:
- Authentication — Scoped access tokens; request the least privilege you need (About Authentication).
- Errors — One machine-readable envelope; match on the stable
code, not the message (Handle errors). - Rate limits — Per-credential limits; read the headers rather than hardcoding numbers (Handle rate limits).
- Pagination — Consistent list models; follow the shared pagination pattern (Paginate results).
- Idempotency — Per-namespace retry rules; check each how-to's Agent Notes before you retry (Building reliable integrations).
Related
Concepts
Last updated on
How is this guide?