# About the Shopping API (https://developer.godaddy.com/en/docs/api-users/shopping)

---
title: About the Shopping API
description: >-
  Authentication, required headers, the checkout state machine, and the error
  model for the Shopping API.
keywords: >-
  shopping API, catalog search, checkout session, checkout state machine,
  error_response, Personal Access Token, Request-Id, Idempotency-Key.
agentNotes:
  permissions:
    - Shopping Catalog
    - Shopping Checkout
    - Shopping Orders
  scopes:
    - 'shopping.catalog:read'
    - 'shopping.checkout:execute'
    - 'shopping.order:read'
  rateLimit: >-
    Rate-limited per credential. Go to /docs/api-users/rate-limits for current
    values.
  failureRecovery: >-
    For 401 or 403 responses, verify the credential, scopes, and expiry. Retry
    an unchanged checkout write with its original Idempotency-Key. Use a new key
    after changing the request.
related:
  guides:
    - title: Search the catalog
      href: /docs/api-users/shopping/guides/search-catalog
    - title: Create a checkout and place an order
      href: /docs/api-users/shopping/guides/purchase
  concepts:
    - title: Handle errors
      href: /docs/api-users/errors
    - title: Rate limits
      href: /docs/api-users/rate-limits
  apis:
    - title: Shopping Catalog reference
      href: /docs/references/rest/shopping/search-catalog
    - title: Shopping Checkout reference
      href: /docs/references/rest/shopping/create-checkout
    - title: Shopping Orders reference
      href: /docs/references/rest/shopping/get-order
---

## Overview

The Shopping API lets platforms browse GoDaddy products, create checkout sessions for buyers, and retrieve completed orders.

## How the API is structured

Three resource groups cover the full purchase flow:

| Resource group | Base path                            | Purpose                                                                   |
| -------------- | ------------------------------------ | ------------------------------------------------------------------------- |
| Catalog        | `/v1/shopping/catalog/...`           | Browse products, retrieve pricing and variant detail                      |
| Checkout       | `/v1/shopping/checkout-sessions/...` | Create sessions, attach buyer identity and payment, complete the purchase |
| Orders         | `/v1/shopping/orders/...`            | Retrieve completed order detail after a checkout completes                |

A typical integration searches the catalog, creates a checkout, selects payment, accepts required agreements, completes the checkout to place an order, and retrieves the order.

## Authentication

Every request needs an `Authorization` header. Generate a Personal Access Token (PAT) with the scopes you need.

| Scope                       | Grants access to                               |
| --------------------------- | ---------------------------------------------- |
| `shopping.catalog:read`     | Catalog search, lookup, and product detail     |
| `shopping.checkout:execute` | Create, update, and complete checkout sessions |
| `shopping.order:read`       | Retrieve completed orders                      |

Go to [How to authenticate](https://developer.godaddy.com/docs/api-users/auth/how-to) for PAT generation and storage.

## Required headers

Every Shopping API request requires these headers in addition to `Authorization`:

| Header            | Required                              | Description                                                                                                                                                                                                  |
| ----------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Request-Id`      | Yes                                   | A unique identifier for tracing the request. Use a UUID per call.                                                                                                                                            |
| `Idempotency-Key` | Yes, on all checkout write operations | Required on `POST /checkout-sessions`, `PUT /checkout-sessions/{id}`, and `POST /checkout-sessions/{id}/complete`. Prevents duplicate operations on retry. Not required on catalog or order read operations. |

The following example sends the common headers:

```bash
Authorization: Bearer $GODADDY_PAT
Request-Id: $(uuidgen)
```

## Checkout state machine

A checkout session uses these states during a successful purchase:

| State                | Meaning                                                                                    |
| -------------------- | ------------------------------------------------------------------------------------------ |
| `incomplete`         | Missing a selected eligible payment instrument or required line-item fields.               |
| `ready_for_complete` | All required fields are present and an eligible payment instrument is selected.            |
| `completed`          | The purchase created an order. The response includes `order.id` and `order.permalink_url`. |

After completion, `GET /orders/{id}` might return `404 order_not_found` while the order read model updates. Retry the order read with bounded backoff.

`GET /checkout-sessions/{id}` might return `404 checkout_not_found` after completion as completed sessions might be cleared. Use the completion response's `order.id` as the purchase confirmation.

## Error responses

The API usually uses HTTP status codes for broad error categories and `messages[].code` for specific conditions. A `2xx` response can also contain an error envelope:

| Status | Meaning                                                               | Example codes                                                              |
| ------ | --------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `400`  | The request is missing or has invalid fields.                         | `invalid_request`, `validation_error`                                      |
| `401`  | The credential is missing, invalid, or expired.                       | Authentication codes can vary by edge.                                     |
| `403`  | The credential lacks the required scope.                              | `insufficient_scope`                                                       |
| `404`  | The product, checkout, or order does not exist or is not visible yet. | `product_not_found`, `checkout_not_found`, `order_not_found`               |
| `422`  | The request is valid JSON but cannot be processed.                    | `item_not_found`, `invalid_domain`, `invalid_term`, `unsupported_currency` |
| `429`  | The caller exceeded a rate limit.                                     | Check `Retry-After` before retrying.                                       |

Error responses use the `error_response` envelope:

```json
{
  "ucp": { "version": "2026-04-08", "status": "error" },
  "messages": [
    {
      "type": "error",
      "code": "invalid_request",
      "content_type": "plain",
      "content": "line_items[0].item.id is required."
    }
  ]
}
```

Successful responses can omit `ucp.status`. Error responses set it to `error`. Check the HTTP status and `ucp.status` on every response, then match `messages[].code`; do not match the human-readable `content`.

Go to [Handle errors](https://developer.godaddy.com/docs/api-users/errors) for GoDaddy's standard error handling guidance.