Search the catalog

Overview

Use the Shopping API v1 Catalog endpoints to browse products, resolve known IDs, and retrieve product detail before checkout.

All catalog operations use shopping.catalog:read scope.

Go to About the Shopping API for required headers and the error model.

Prerequisites

The following prerequisites are required before you can search the catalog:

• a PAT with shopping.catalog:read scope
• jq and uuidgen for the curl examples

Authenticate

These examples use a $GODADDY_PAT with shopping.catalog:read scope.

Go to About the Shopping API for the full list of required scopes.

Search products

POST /v1/shopping/catalog/search returns products matching a free-text query or filters. Use this endpoint to show buyers a browsable product list.

The following procedure searches the product catalog.

• Search for available products:

  curlNodePythonGo

  curl --fail-with-body --silent --show-error -X POST "https://api.godaddy.com/v1/shopping/catalog/search" \
    -H "Authorization: Bearer $GODADDY_PAT" \
    -H "Request-Id: $(uuidgen)" \
    -H "Content-Type: application/json" \
    -d '{
      "context": { "address_country": "US", "currency": "USD", "language": "en" },
      "pagination": { "limit": 20 }
    }'

• Search for hosting products by keyword:

  curlNodePythonGo

  curl --fail-with-body --silent --show-error -X POST "https://api.godaddy.com/v1/shopping/catalog/search" \
    -H "Authorization: Bearer $GODADDY_PAT" \
    -H "Request-Id: $(uuidgen)" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "hosting",
      "context": { "address_country": "US", "currency": "USD", "language": "en" },
      "pagination": { "limit": 20 }
    }'

Use pagination.cursor from the response and pass it in pagination.cursor on the next request to page through results when has_next_page is true.

Look up products by ID

POST /v1/shopping/catalog/lookup fetches one or more specific variants by their IDs. Use this when you already know the variant ID and need current pricing and availability.

The following procedure looks up variants by ID.

• Look up specific variants:

  curlNodePythonGo

  curl --fail-with-body --silent --show-error -X POST "https://api.godaddy.com/v1/shopping/catalog/lookup" \
    -H "Authorization: Bearer $GODADDY_PAT" \
    -H "Request-Id: $(uuidgen)" \
    -H "Content-Type: application/json" \
    -d "$(jq -n --arg id "$VARIANT_ID" '{"ids":[$id],"context":{"address_country":"US","currency":"USD","language":"en"}}')"

Each returned variant includes an inputs[] array showing how the variant matched the requested ID — either exact or featured.

Get product detail

POST /v1/shopping/catalog/product retrieves one product and its available variants. The current catalog does not use option-selection narrowing, so send only id and optional context.

The following procedure retrieves product detail.

• Get detail for a specific product:

  curlNodePythonGo

  curl --fail-with-body --silent --show-error -X POST "https://api.godaddy.com/v1/shopping/catalog/product" \
    -H "Authorization: Bearer $GODADDY_PAT" \
    -H "Request-Id: $(uuidgen)" \
    -H "Content-Type: application/json" \
    -d "$(jq -n --arg id "$VARIANT_ID" '{"id":$id,"context":{"address_country":"US","currency":"USD","language":"en"}}')"

Interpret catalog results

Catalog amounts use ISO 4217 minor units. For USD, an amount of 999 represents $9.99.

Verify the result

Confirm that the selected variant has availability.available: true, a price in the expected currency, and any required product input.

Save the variant ID for checkout. Go to Create a checkout and place an order to purchase it.

Example response

The search endpoint returns a products[] array. Each product contains a variants[] array. Use variants[].id to create a checkout session:

{
  "products": [
    {
      "id": "hosting-economyapi",
      "title": "Economy Hosting",
      "variants": [
        {
          "id": "hosting-economyapi:1mo",
          "title": "Economy 1 Month",
          "price": { "amount": 999, "currency": "USD" },
          "availability": { "available": true }
        }
      ]
    }
  ],
  "pagination": { "has_next_page": false }
}

Common errors

Last updated on