About the Commerce API
View as MarkdownBuild integrations to manage stores, catalogs, orders, customers, and taxes with GoDaddy Commerce.
Overview
Use the Commerce API to manage stores, catalogs, orders, customers, and taxes.
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
GoDaddy Payments is a separate account from your standard GoDaddy account. Creating a GoDaddy Payments account creates a GoDaddy business entity and a default store simultaneously. The storeId is generated automatically as part of that process.
There's no API to create a GoDaddy Payments account or a store. You must set up a GoDaddy Payments account through the UI.
Go to GoDaddy Payments for an overview of what's included.
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. The header is required. 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). GraphQL versions are visible in the endpoint paths above.
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?