# About the Auctions API (https://developer.godaddy.com/en/docs/api-users/auctions) --- title: About the Auctions API description: >- How the Auctions API is structured, what it covers, and how the core resources relate to each other. keywords: >- customerId MY alias, listingId, paymentProfileId, bidId, 207 multi-status, micro-units, sso-key legacy API key, expiring auction, closeout auction, Buy Now aftermarket, domain lifecycle day 26-41 related: concepts: - title: How GoDaddy APIs work href: /docs/api-users/concepts/how-godaddy-apis-work guides: - title: Buy a closeout auction via instant purchase href: /docs/api-users/buy-a-domain/instant-purchase - title: Place bids on expiring auctions href: /docs/api-users/buy-a-domain/bidding - title: Set up a payment profile href: /docs/api-users/payment-profile --- ## Overview The Auctions API covers two ways to acquire expiring domains on the GoDaddy platform: bidding on expiring auctions and instant purchase of closeouts (Buy Now) auctions at a fixed price. Both capabilities use v1 endpoints and require a `customerId` path parameter. You can use the `MY` alias to target the authenticated customer's own account. Personal Access Tokens (PAT) aren't supported for Auctions API endpoints. Use a [Classic Developer Key](https://classic-developer.godaddy.com/keys) and pass it as `Authorization: sso-key $GODADDY_API_KEY`. Go to [How to Authenticate](https://developer.godaddy.com/docs/api-users/auth/how-to) and follow the Classic Developer Key tab. ## How the API is structured The following sections describe how the Auctions API is structured. ### Single version namespace All endpoints are located under `/v1/customers/{customerId}/...`. Authenticate with a [Classic Developer Key](https://classic-developer.godaddy.com/keys) and pass the customer's ID (or `MY`) in the path. ### Your customer ID The `customerId` path parameter is a UUID. It's different from the shorter numeric GoDaddy shopper ID. For most integrations, pass `MY` and the API resolves it to your authenticated account automatically. If you need the UUID explicitly (for example, to store or display it) call the Shoppers API: ```bash curl -s "https://api.godaddy.com/v1/shoppers/MY?includes=customerId" \ -H "Authorization: sso-key $GODADDY_API_KEY" ``` The `customerId` field in the response is your UUID. If you manage another account (reseller use case), replace `MY` with that account's numeric GoDaddy shopper ID (up to 10 digits). The account holder can find their shopper ID in their GoDaddy account settings. ```bash curl -s "https://api.godaddy.com/v1/shoppers/{shopperId}?includes=customerId" \ -H "Authorization: sso-key $GODADDY_API_KEY" ``` ### 207 partial success Both the bidding and instant purchase endpoints accept arrays of items and process each independently. When some items succeed and others fail, the API returns `207 Multi-Status`, not a 4xx error. Inspect each item's `status` field individually: * `status: "SUCCESS"`: the item was processed successfully * `status: "FAILED"`: check `failureReason` for the machine-readable cause A 200 means every item in the array succeeded. A 207 means at least one failed. Failed items are safe to retry. Don't re-submit items that already returned `SUCCESS`. ### Pricing in micro-units All monetary amounts are integers in micro-units (amount × 10⁶). For USD: | Micro-units | Dollar amount | | ----------- | ------------- | | `50000000` | $50.00 | | `61990000` | $61.99 | | `100000000` | $100.00 | Divide by `1,000,000` to get the human-readable price. ## Core resources The following sections describe the core resources of the Auctions API. ### Listing An auctions listing represents a domain available for purchase on the GoDaddy Auctions marketplace. Listings have a `listingId` (integer) used when placing bids, and a `domainName` used for instant purchase and availability checks. ### Payment profile A payment profile is a saved payment method eligible for API-initiated purchases. Only `ACTIVE` profiles are returned by `GET /v1/customers/{customerId}/paymentProfiles`. Credit cards and prepaid methods are supported. ### Bid A bid is a price offer placed on an expiring auction listing. Bid amounts are in USD micro-units. The response indicates whether you're the highest bidder and provides a `bidId` for tracking. ### Purchase A purchase represents a completed instant purchase transaction. The response includes an `orderId` and per-domain results. `totalPrice` is the amount charged, in micro-units. ## Lifecycle of an expiring domain Most auctions listings aren't deliberate seller listings — they're domains that lapsed through GoDaddy's or a partner registrar's standard expiration process. Where a domain sits in that timeline determines which capability applies: bidding while it's an expiring auction, instant purchase once it moves to a closeout (Buy Now). The following diagram shows that path: | Phase | Timing | What it means for this API | | -------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Grace period | Day 0–18 | Not listed. Domain isn't reachable through Auctions yet. | | Redemption period | Day 18–26 | Still not listed. The original owner can recover it directly, outside this API. | | Expiring Auction | Day 26–36 | The domain gets a `listingId` and becomes visible to [Check listing availability](https://developer.godaddy.com/docs/api-users/buy-a-domain/bidding#check-listing-availability). Use [bidding](https://developer.godaddy.com/docs/api-users/buy-a-domain/bidding) to compete for it. | | Closeout Auction | Day 36–41 | If nobody bid on the expiring auction, the listing becomes a closeout auction. Use [instant purchase](https://developer.godaddy.com/docs/api-users/buy-a-domain/instant-purchase) to buy it outright. | | Removed from account | Day 72 | Point of no return for the original owner. The registry eventually releases the domain for new registration outside Auctions. | These day counts follow GoDaddy's general gTLD expiration policy. ccTLDs and some other TLDs run different timelines. Go to [the domain lifecycle](https://developer.godaddy.com/docs/api-users/domains/concepts#the-domain-lifecycle) for the broader (non-auction) picture, and GoDaddy's [standard domain expiration timeline](https://www.godaddy.com/help/standard-domain-expiration-timeline-609) for the full day-by-day breakdown. For domains that lapsed directly with GoDaddy, the original owner loses the ability to redeem at Day 30. For domains that came through a partner registrar, that cutoff depends on GoDaddy's contractual agreement with that registrar. Redemption might still be possible past Day 30. Either way, a `listingId` from an earlier availability check isn't guaranteed to still be valid. Re-check availability before bidding if time has passed, and treat a `LISTING_NOT_FOUND` error the same way you'd treat any other retryable [207 failure](#207-partial-success). GoDaddy Auctions Inventory Files are downloadable datasets (ZIP, XML, and JSON) containing bulk information on live expired auctions and closeout listings. Use them to identify and analyze domains before placing bids or making purchases through the API. Go to the [Auctions Inventory page](https://inventory.auctions.godaddy.com/) to download Inventory Files. ## Bidding vs. instant purchase The following table compares bidding and instant purchase: | | Bidding | Instant purchase | | ------------ | ------------------------------------------------- | ------------------------------------------------------------------ | | Auction type | Open English auction | Closeout (Buy Now fixed-price) | | Outcome | Win or lose at auction close | Immediate, domain fulfills on success | | Price | Your bid in USD micro-units | All-in total: auction price + renewal/transfer + ICANN fee + taxes | | Payment | Charged on auction win | Charged at time of purchase | | Reversible | Not reversible, charges are due if auction is won | Not reversible, charges are immediate | ## Operations by task The following table lists the operations by task: | Task | Endpoint | Workflow | | -------------------------------- | ---------------------------------------------------------------- | ----------------------------------------------------------------------------- | | Check listing availability | `POST /v1/customers/{customerId}/aftermarket/listings/available` | [Place bids](https://developer.godaddy.com/docs/api-users/buy-a-domain/bidding) | | Place bids | `POST /v1/customers/{customerId}/aftermarket/listings/bids` | [Place bids](https://developer.godaddy.com/docs/api-users/buy-a-domain/bidding) | | Get eligible payment profiles | `GET /v1/customers/{customerId}/paymentProfiles` | [Buy through instant purchase](https://developer.godaddy.com/docs/api-users/buy-a-domain/instant-purchase) | | Preview instant purchase pricing | `POST /v1/customers/{customerId}/auctions/purchases/preview` | [Buy through instant purchase](https://developer.godaddy.com/docs/api-users/buy-a-domain/instant-purchase) | | Execute instant purchase | `POST /v1/customers/{customerId}/auctions/purchases` | [Buy through instant purchase](https://developer.godaddy.com/docs/api-users/buy-a-domain/instant-purchase) | # Handle errors (https://developer.godaddy.com/en/docs/api-users/errors) --- title: Handle errors description: 'Error response shape, status code semantics, and retry guidance.' keywords: >- 400 401 403 404 422 429 500, UNABLE_TO_AUTHENTICATE, requestId, error envelope, exponential backoff, idempotency key agentNotes: scopes: - Any — applies to all API operations rateLimit: N/A (informational reference) failureRecovery: >- Match the 'code' field, not HTTP status, for programmatic handling. 4xx errors are client-fixable (check input, scopes, payment profile). 5xx errors are safe to retry with exponential backoff. 429 means wait for Retry-After header. related: guides: - title: Handle rate limits href: /docs/api-users/rate-limits - title: Authentication href: /docs/api-users/auth - title: Set up a payment profile href: /docs/api-users/payment-profile - title: About the Shopping API href: /docs/api-users/shopping apis: - title: Domains v3 reference href: /docs/references/rest/domains/v3 - title: Domains v1 reference href: /docs/references/rest/domains/v1 - title: Hosting API reference href: /docs/references/rest/hosting --- ## Overview GoDaddy REST APIs return a consistent error envelope. Every error response includes a stable `code` field for programmatic handling, and optionally field-level validation details. This page covers the response shape, status code semantics, and retry guidance for GoDaddy REST APIs — including the Domains, Auctions, and Hosting APIs. The Shopping API does not follow this standard error model. Go to [Shopping API error responses](#shopping-api-error-responses) for its behavior. ## Error response shape `Error` schema (used for 4xx and 5xx responses): ```json { "code": "INVALID_BODY", "message": "Request body did not match the expected schema.", "fields": [ { "path": "contactRegistrant.email", "code": "INVALID_FORMAT", "message": "Value must be a valid email address." } ] } ``` | Field | Required | Description | | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | `code` | Yes | Stable, machine-readable error code. Match on this for programmatic handling. | | `message` | No | Human-readable message. It might change between releases. | | `fields[]` | No | Per-field validation details when the error is body- or query-scoped. Each entry has its own `path` (JSONPath into the request), `code`, and `message`. | `ErrorLimit` extends `Error` with one additional field for rate-limit (`429`) responses: | Field | Required | Description | | --------------- | -------- | ----------------------------------------------------------------------------------------------------------------- | | `retryAfterSec` | Yes | Seconds the caller should wait before retrying the same operation. Mirrored in the `Retry-After` response header. | ## Status codes | Status | Meaning | Caller action | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- | | `400 Bad Request` | Request was malformed (missing required field, invalid query parameter format). | Fix the request. Inspect `fields[]` for specifics. | | `401 Unauthorized` | `Authorization` header missing, malformed, expired, or revoked. | Re-authenticate. See [Authentication](https://developer.godaddy.com/docs/api-users/auth). | | `403 Forbidden` | Authenticated but unauthorized — usually a missing scope or insufficient role. | Issue a token with the required scope, or escalate the calling principal's authorization. | | `404 Not Found` | The path doesn't exist, or the addressed resource (domain, contact, record) isn't visible to this caller. | Verify the path and confirm the caller owns or can access the resource. | | `409 Conflict` | The request conflicts with current state (e.g. registering a name already taken; updating a record set that's mid-transfer). | Re-read state and retry only after resolving the conflict. | | `422 Unprocessable Entity` | Request was syntactically valid but semantically rejected (e.g. invalid registrant data, TLD-specific constraint failure, `NO_PAYMENT_PROFILE`). | Inspect `code` and `fields[]`. For missing billing, see [Set up a payment profile](https://developer.godaddy.com/docs/api-users/payment-profile). | | `429 Too Many Requests` | Rate limit exceeded. Domains and Auctions shape the response as `ErrorLimit`. | Wait the seconds given by the `Retry-After` header, then retry. Go to [Handle rate limits](https://developer.godaddy.com/docs/api-users/rate-limits) for strategies. | | `5xx Server Error` | Upstream registry or service issue. | Retry idempotent operations with exponential backoff. See [Retry semantics](#retry-semantics) for non-idempotent ones. | ## Retry semantics The following sections describe the retry semantics for read and write operations using Domains API endpoints. The same retry semantics apply across GoDaddy REST APIs. Endpoint paths will vary by API. ### Read operations All `GET` operations are safe to retry. Domains API examples: * `GET /v3/domains/check-availability` — availability check * `GET /v1/domains` — list your domains * `GET /v1/domains/{domain}` — domain detail * `GET /v1/domains/{domain}/records` — DNS records ### Write operations Most Domains writes can be retried after a 5xx, but **the Domains API doesn't support an `Idempotency-Key` request header** — neither v1 nor v2 specs declare one. This affects retry strategy on a few specific operations: | Operation | Retry-safe? | | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `POST /v1/domains/purchase` | **Not idempotent without external coordination.** A retry can result in a duplicate registration if the first attempt actually succeeded server-side. Pair every retry with a fresh `GET /v1/domains/available` and a state check via `GET /v1/domains/{domain}`. | | `POST /v1/domains/{domain}/renew` | Idempotent within a billing cycle in practice — the registry rejects duplicates — but treat the same as `purchase`: confirm state before retrying. | | `POST /v1/domains/{domain}/transfer` | Same as `purchase`. | | `PUT /v1/domains/{domain}/records` (replace) | Idempotent by shape — replaying the same request produces the same record set. | | `PATCH /v1/domains/{domain}/records` (add) | **Not idempotent** — repeated calls add duplicate records. | | `DELETE /v1/domains/{domain}/records/{type}/{name}` | Idempotent — deleting an already-deleted record is a no-op. | ### Async write operations The Hosting API returns `202 Accepted` for most write operations. The caller must poll a status endpoint until the operation reaches a terminal state. Retry semantics differ from synchronous writes: | Operation | Idempotent? | Terminal states | Retry guidance | | -------------------------------- | --------------------------------------------------------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------- | | `POST /v1/hosting/apps` | No — each call creates a new app | `COMPLETED`, `FAILED` | On 5xx or network failure, check `GET /apps` before retrying — a partial success may have provisioned the app. | | `POST /apps/{appId}/imports` | Yes — each upload overwrites the preview variant | `COMPLETED`, `FAILED` | Safe to retry. The latest upload always wins. | | `POST /apps/{appId}/deployments` | Yes within the same source — republishing the same preview is a no-op | `COMPLETED`, `FAILED` | Safe to retry. If status stays `FAILED`, fetch build logs before retrying. | ## Programmatic error handling Match on `code`, not `message`. Codes are stable across releases; messages might be refined. The codes below are specific to the Domains API. Check your API's OpenAPI specification for its error codes. ```js const res = await fetch(url, { headers }); if (!res.ok) { const err = await res.json(); switch (err.code) { case "DOMAIN_NOT_AVAILABLE": // someone else registered the name first break; case "BILLING_DECLINED": // payment method failed — surface to user break; case "NO_PAYMENT_PROFILE": // no billing method on account — see payment profile setup break; default: // log err.code and err.fields for debugging throw new Error(err.code + ": " + err.message); } } ``` Reference: the `Error` and `ErrorLimit` schemas are defined in the OpenAPI specification. ## Shopping API error responses The Shopping API usually maps errors to HTTP status codes. A `2xx` response can also contain an error envelope, so check the status and `messages[].code` on every response. ```json { "ucp": { "version": "2026-04-08", "status": "error" }, "messages": [ { "type": "error", "code": "validation_error", "content_type": "plain", "content": "line_items[0].item.id is required." } ] } ``` | Field | Description | | -------------------- | --------------------------------------------------------------------------------- | | `ucp.status` | `"error"` when the request failed. Successful responses can omit this field. | | `messages[].code` | Stable, machine-readable error code. Match on this programmatically. | | `messages[].content` | Human-readable description. It might change between releases; do not match on it. | Common codes include `invalid_request`, `validation_error`, `product_not_found`, `checkout_not_found`, `order_not_found`, `item_not_found`, and `unsupported_currency`. ```js const res = await fetch(url, { headers }); const body = await res.json(); // Check the HTTP status and the error marker. if (!res.ok || body?.ucp?.status === "error") { const code = body?.messages?.[0]?.code; switch (code) { case "validation_error": // fix the line item and retry break; case "item_not_found": // choose a current purchasable variant break; default: throw new Error(`Shopping API error: ${code}`); } } ``` Go to [About the Shopping API](https://developer.godaddy.com/docs/api-users/shopping#error-responses) for the Shopping status and code reference. # Glossary (https://developer.godaddy.com/en/docs/api-users/glossary) --- title: Glossary description: Definitions for terms used throughout the GoDaddy API documentation. keywords: >- async operation 202 poll, Classic Developer Key sso-key, Good as Gold prepaid balance, idempotency key UUID, mailbox provisioning entitlement, OTE sandbox environment, payment request checkout session, quote token expiry, rate limit 429 retry, redemption period recovery, registry lock out-of-band, scope bundle PAT picker, SKU fulfillment order status, status polling exponential backoff, TTL minimum 600 related: guides: - title: Authenticate href: /docs/api-users/auth - title: Rate limits href: /docs/api-users/rate-limits - title: Error handling href: /docs/api-users/errors - title: Manage orders and customers href: /docs/api-users/commerce/manage-orders-and-customers --- Learn about the terms used throughout the GoDaddy API documentation. Entries cover concepts that apply across all APIs as well as terms specific to [Domains](https://developer.godaddy.com/docs/api-users/domains), [Commerce](https://developer.godaddy.com/docs/api-users/commerce), and [Email](https://developer.godaddy.com/docs/api-users/email). API-specific terms are labeled *(Domains)*, *(Commerce)*, or *(Email)* in the Term column. Unlabeled terms apply across all GoDaddy REST APIs. | Term | Definition | | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **async operation** | An API operation that returns `202 Accepted` immediately and continues processing in the background. The caller receives an operation ID and polls a status endpoint until the operation reaches `COMPLETED` or `FAILED`. Domain registration, domain transfers, and mailbox provisioning use async operations. See [status polling](#status-polling). | | **authoritative nameserver** *(Domains)* | The nameserver that holds the definitive DNS records for a domain. When you update DNS records through the GoDaddy API, the change is applied to GoDaddy's authoritative nameservers. External resolvers cache the previous values until the TTL expires. See [TTL](#ttl-time-to-live). | | **channel** *(Commerce)* | A sales surface through which orders are placed. Values: `ONLINE` (web storefront), `RETAIL` (physical location), `MOBILE` (app), `MARKETPLACE` (Amazon, eBay), `SOCIAL` (Facebook, Instagram). Each channel has a unique `channelId` used when querying orders. | | **checkout session** *(Commerce)* | A Commerce object representing an active cart and payment context. Managed through the `commerce.checkout-session:read/write` scopes. Part of the Payments API surface. See [payment request](#payment-request). | | **Classic Developer Key** *(Domains, Auctions)* | A credential pair (API key and secret) used in the format `Authorization: sso-key :`. Required for the Auctions API and supported (but deprecated) for Domains v1/v2 endpoints. Not accepted by the v3 Domains API, Commerce, or Email APIs. See [PAT (Personal Access Token)](#pat-personal-access-token). | | **CNAME (Canonical Name record)** *(Domains)* | A DNS record type that aliases one domain name to another. A CNAME cannot coexist with other records at the same name — a CNAME at the apex (`@`) is invalid when other records (A, MX) are present. | | **domain status** *(Domains)* | The lifecycle state of a registered domain. Common values: `ACTIVE` (in use), `CANCELLED` (registration lapsed), `PENDING_TRANSFER` (outbound transfer in progress), `EXPIRED` (past expiration, in grace period), `REDEMPTION` (past grace period, recoverable at higher cost). Status values affect which API operations are permitted. | | **domain transfer** *(Domains)* | Moving a domain registration from one registrar to another. Outbound transfers require an authorization code (EPP code). Transfers take up to 5–7 days to complete and go through `PENDING_TRANSFER` status during that time. | | **entitlement** *(Email)* | A provisioning credit tied to a domain that authorizes creation of one or more mailboxes. Check the `eligibleAccounts` field returned by the check-eligibility endpoint to see available entitlements and any consent requirements before provisioning a mailbox. | | **fulfillment** *(Commerce)* | The process of delivering order line items to a customer. Each line item has a fulfillment mode: `SHIP` (physical shipment), `PICKUP` (in-store collection), or `DIGITAL` (electronic delivery). Fulfillment state is tracked through a [fulfillment plan](#fulfillment-plan). | | **fulfillment plan** *(Commerce)* | An object created automatically when an order transitions from `DRAFT` to `OPEN`. It lists the line items to fulfill and their fulfillment modes. Referenced by `fulfillmentPlanId` and accessed through the `commerce.fulfillment-plan:read` scope. | | **Good as Gold** | GoDaddy's prepaid balance program. Some accounts can use a Good as Gold balance to fund API operations that cost money (domain registration, renewal, transfer). If an account has neither a payment method nor a Good as Gold balance, write operations that require payment return `403 Forbidden`. Go to [Set up a payment profile](https://developer.godaddy.com/docs/api-users/payment-profile) for more information. | | **grace period** *(Domains)* | A period after domain expiration during which the domain can be renewed at normal pricing. After the grace period ends, the domain enters a redemption period and renewal costs increase significantly. | | **ICANN consent** *(Domains)* | The Internet Corporation for Assigned Names and Numbers (ICANN) requires registrants to confirm that their contact information is accurate before a domain is registered. In the v3 API, you provide this as a consent object in the registration request. Providing false information can result in domain suspension. | | **idempotency key** | A client-generated value (typically a UUID) included in the `Idempotency-Key` request header. If the server already processed a request with the same key, it returns the original response without executing the operation again. Use idempotency keys on all non-idempotent write operations — particularly domain registration and mailbox provisioning — to prevent duplicate charges or duplicate resource creation on retries. | | **mailbox** *(Email)* | A GoDaddy-hosted email address managed through the Email API. Each mailbox is identified by a `mailboxId`, associated with a domain you own, and hosted on GoDaddy's Titan email platform. See [provisioning](#provisioning) and [mailbox status](#mailbox-status). | | **mailbox status** *(Email)* | The lifecycle state of a mailbox provisioning operation. Values: `CONFIRMED` (creation initiated), `EXECUTING` (provisioning in progress), `COMPLETED` (mailbox ready to use), `FAILED` (provisioning failed). Poll the mailbox endpoint until status reaches `COMPLETED` or `FAILED`. See [async operation](#async-operation). | | **MX record (Mail Exchanger record)** *(Domains)* | A DNS record type that specifies the mail servers responsible for accepting email for a domain. MX records include a priority value — lower numbers indicate higher priority. | | **nameserver** *(Domains)* | A server that answers DNS queries for a domain. Nameservers are authoritative (hold the definitive records) or recursive (resolve queries by querying authoritative servers on behalf of clients). Changing a domain's nameservers delegates DNS management to a different provider. | | **NS record (Name Server record)** *(Domains)* | A DNS record type that delegates a DNS zone to a set of nameservers. GoDaddy-managed NS records cannot be modified through the DNS records API — use the dedicated nameservers endpoint instead. | | **OTE (Operational Test Environment)** | GoDaddy's sandbox environment for testing integrations. Base URL: `https://api.ote-godaddy.com`. Requests in OTE do not process real transactions or charge real accounts. Not all APIs offer an OTE environment — check the documentation for the API you are testing. OTE credentials are separate from production credentials. | | **PAT (Personal Access Token)** | A scoped Bearer token used to authenticate API requests. Generated from the [developer dashboard](https://developer.godaddy.com/personal-access-token). PATs are the recommended credential wherever an API accepts one and are required for v3 Domains API access. A PAT includes one or more scopes (for example, `domains.domain:read`, `commerce.order:read`) that determine which operations it can authorize. Go to [Authenticate](https://developer.godaddy.com/docs/api-users/auth) for the full credential guide. | | **payment request** *(Commerce)* | A Commerce object representing a request to collect payment for a purchase. Managed through the `commerce.payment-request:read/write` scopes. See [checkout session](#checkout-session). | | **provisioning** *(Email)* | The async process of creating a mailbox on GoDaddy's email platform. Submit a creation request, then poll for [mailbox status](#mailbox-status) until the operation reaches `COMPLETED` or `FAILED`. Use an [idempotency key](#idempotency-key) to prevent duplicate mailboxes on retried requests. See [async operation](#async-operation). | | **quote token** *(Domains)* | A short-lived token returned by `POST /v3/domains/registration-quotes`. The token locks the price for a domain registration and must be included in the subsequent `POST /v3/domains/registrations` call. Quote tokens expire quickly — re-quote if you receive a `QUOTE_EXPIRED` error. | | **rate limit** | The maximum number of API requests allowed per credential per time window. GoDaddy REST APIs currently limit requests to 600 per approximately 23-minute window per credential, though this value is subject to change. Exceeding the limit returns `429 Too Many Requests`. Read `RateLimit-Remaining` from response headers to track usage in real time rather than assuming a fixed number. Go to [Handle rate limits](https://developer.godaddy.com/docs/api-users/rate-limits) for retry guidance. | | **redemption period** *(Domains)* | A period after the grace period ends during which a domain can still be recovered, but at significantly higher cost. After the redemption period, the domain is released for re-registration by anyone. | | **registrar** *(Domains)* | A company accredited by ICANN to sell and manage domain registrations. GoDaddy is a registrar. The registrar manages the relationship with the registry on behalf of the registrant (the domain owner). | | **registry** *(Domains)* | The organization that manages a top-level domain (TLD) on behalf of ICANN. For example, Verisign manages `.com` and `.net`; the Public Interest Registry manages `.org`. The registry maintains the authoritative database of all domains under the TLD. | | **registry lock** *(Domains)* | A security feature that prevents unauthorized changes to a domain's nameservers, contact information, or transfer status by requiring out-of-band verification. Domains with registry lock cannot be updated programmatically until the lock is released. | | **scope** | A permission granted to a PAT that authorizes a specific category of API operations. Every API area has its own scope namespace: `domains.*` for Domains, `commerce.*` for Commerce, `email.*` for Email. For example, `domains.domain:read` allows read-only domain queries; `commerce.order:read` allows reading Commerce orders. A PAT must include all scopes required for each operation it performs. Go to [Authenticate — PAT scopes](https://developer.godaddy.com/docs/api-users/auth#pat-scopes) for the full reference. | | **scope bundle** | A named group of related PAT scopes selectable as a unit in the [developer dashboard](https://developer.godaddy.com/personal-access-token) token picker. For example, the **Domains & DNS** bundle selects all `domains.*` scopes at once. Selecting a bundle is equivalent to selecting each scope individually. Go to [Authenticate — PAT scopes](https://developer.godaddy.com/docs/api-users/auth#pat-scopes) for available bundles. | | **shopper ID / customer ID** *(Domains)* | GoDaddy's internal identifier for an account. In the v2 API, the `customerId` appears in operation paths (`/v2/customers/{customerId}/domains/...`). In the v3 API, the authenticated credential determines the account — no customer ID is required in the path. | | **SKU (Stock Keeping Unit)** *(Commerce)* | A single purchasable product variant — for example, a shirt in size M. Related SKUs are grouped into a SKU group (a product). An individual SKU is referenced by `skuId`; the group is referenced by `skuGroupId`. SKUs are managed through the Commerce catalog endpoints. | | **SOA record (Start of Authority record)** *(Domains)* | A DNS record that contains administrative information about a DNS zone, including the primary nameserver, zone serial number, and refresh intervals. SOA records are managed by GoDaddy and cannot be modified through the API. | | **status polling** | The process of repeatedly calling a status endpoint to check whether an async operation has completed. The recommended pattern is exponential backoff: wait 1 second, then 2, then 4, up to a reasonable maximum. Stop polling when status reaches `COMPLETED` or `FAILED`. See [async operation](#async-operation). | | **storeId** *(Commerce)* | The UUID uniquely identifying a GoDaddy Payments store. Required as the `x-store-id` header on all Commerce API calls. If you receive `403 Forbidden` on Commerce endpoints, verify you are sending the correct `storeId` for the merchant account. | | **TXT record** *(Domains)* | A DNS record type that stores arbitrary text associated with a domain. TXT records are commonly used for domain ownership verification (Google, GitHub, Stripe), SPF email authentication, and DKIM keys. | | **TTL (Time to Live)** *(Domains)* | The number of seconds a DNS record can be cached by resolvers before they must re-query the authoritative nameserver. Lower TTLs reduce propagation time for changes but increase query volume. The minimum TTL for GoDaddy-hosted DNS is 600 seconds (10 minutes). | | **v1 / v2 / v3 API** *(Domains)* | The three versioned namespaces of the GoDaddy Domains API. `v1` (`/v1/domains/...`) covers DNS, contacts, renewals, lock, and transfers. `v2` (`/v2/customers/{customerId}/domains/...`) adds async operation tracking. `v3` (`/v3/domains/...`) is the preferred namespace for new integrations — it separates quoting from execution, supports async operations, and requires ICANN consent. Go to the [Domains API overview](https://developer.godaddy.com/docs/references/rest/domains) for the version comparison table. | | **zone** *(Domains)* | The complete set of DNS records for a domain managed by a single authoritative nameserver. Managing DNS through the GoDaddy API operates on a domain's zone. If the domain uses external nameservers, GoDaddy's zone is inactive — DNS records must be managed at the external provider. | # Introduction (https://developer.godaddy.com/en/docs/api-users) --- title: Introduction description: 'Call GoDaddy''s REST APIs directly from your code, scripts, or AI agents.' keywords: >- REST API overview, v1 v2 v3, OTE, sandbox, sso-key, base URL, developer platform, HTTP API related: guides: - title: Quickstart href: /docs/api-users/quickstart - title: Authenticate href: /docs/api-users/auth - title: Set up the CLI href: /docs/api-users/cli/set-up - title: Agent skill for gddy href: /docs/api-users/cli/agent-skill - title: Buy or bid on a domain href: /docs/api-users/buy-a-domain/instant-purchase - title: About the Shopping API href: /docs/api-users/shopping - 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 --- ## Overview GoDaddy's REST APIs give you direct programmatic access to the same platform capabilities that power GoDaddy's own products — through standard HTTP calls from your code, scripts, or AI agents. | API | What you can do | | ------------------------------------ | ----------------------------------------------------------------------------------------------------- | | [Auctions](https://developer.godaddy.com/docs/api-users/auctions) | Buy expired or expiring domains at a fixed price or through open bidding. | | [Commerce](https://developer.godaddy.com/docs/api-users/commerce) | Work directly with stores, catalog, customers, orders, and tax. | | [Domains](https://developer.godaddy.com/docs/api-users/domains) | Search and register domains, manage DNS, renewals, transfers, and forwarding. | | [Email](https://developer.godaddy.com/docs/api-users/email) | Provision and manage GoDaddy-hosted mailboxes for domains you own. | | [Hosting](https://developer.godaddy.com/docs/api-users/hosting) | Deploy and operate Node.js apps without a dashboard. | | [Shopping](https://developer.godaddy.com/docs/api-users/shopping) | Browse GoDaddy products, create checkout sessions on behalf of buyers, and retrieve completed orders. | ## Get started **Auctions** Buy expired or expiring domains at a fixed price or through open bidding. * [Buy or bid on a domain](https://developer.godaddy.com/docs/api-users/buy-a-domain/instant-purchase) — purchase at a fixed price or place bids on open auction listings. **Commerce** Work directly with GoDaddy stores, catalog, customers, orders, and tax — for your own business or as a third-party app (with the merchant's consent). * [Set up a store](https://developer.godaddy.com/docs/api-users/commerce/set-up-a-store) — configure a store, business entity, and sales channels. * [Manage your catalog](https://developer.godaddy.com/docs/api-users/commerce/manage-catalog) — create and manage products. * [Manage orders and customers](https://developer.godaddy.com/docs/api-users/commerce/manage-orders-and-customers) — process orders, transactions, and customer records. * [Configure taxes](https://developer.godaddy.com/docs/api-users/commerce/configure-taxes) — set up tax rates. **Domains** Search and register domains, manage DNS, renewals, transfers, and forwarding. * [Search for domains](https://developer.godaddy.com/docs/api-users/domains/search) — check availability, compare pricing, and discover suggestions. * [Purchase domains](https://developer.godaddy.com/docs/api-users/domains/register) — register a new domain or transfer one from another registrar. * [Manage your domains](https://developer.godaddy.com/docs/api-users/domains/manage) — DNS, contacts, renewals, lock, and forwarding. **Email** Provision and manage GoDaddy-hosted mailboxes for domains you own. * [Provision mailboxes](https://developer.godaddy.com/docs/api-users/email/mailboxes/provision-mailboxes) — check eligibility and create mailboxes for your domains. * [Manage mailboxes](https://developer.godaddy.com/docs/api-users/email/mailboxes/manage-mailboxes) — list and look up mailboxes across your domains. **Hosting** Deploy and operate Node.js apps without a dashboard. * [Manage apps](https://developer.godaddy.com/docs/api-users/hosting/manage-apps) — create, update, and delete hosted applications. * [Manage secrets](https://developer.godaddy.com/docs/api-users/hosting/manage-secrets) — store and rotate environment secrets. * [Read logs](https://developer.godaddy.com/docs/api-users/hosting/read-logs) — stream and query application logs. **Shopping** Browse GoDaddy's product catalog, create checkout sessions for buyers, and retrieve completed orders. Direct integrations can authenticate with a PAT. * [About the Shopping API](https://developer.godaddy.com/docs/api-users/shopping) — authentication, required headers, and the error model. * [Search the catalog](https://developer.godaddy.com/docs/api-users/shopping/guides/search-catalog) — browse products and look up variants by ID. * [Create a checkout and place an order](https://developer.godaddy.com/docs/api-users/shopping/guides/purchase) — create a session, add buyer and payment details, and complete the purchase. ## Base URL All API calls target `https://api.godaddy.com`. All requests and responses use JSON. Every call requires an `Authorization` header. Most APIs take a [Personal Access Token](https://developer.godaddy.com/docs/api-users/auth), but some require a Classic Developer Key instead. Review the [authentication requirements](https://developer.godaddy.com/docs/api-users/auth) for the API you're calling. Read operations also need `Accept: application/json`, and write operations (`POST`, `PATCH`, `PUT`) additionally need `Content-Type: application/json`. ```bash curl -s "https://api.godaddy.com/v1/domains" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "Accept: application/json" ``` The API is stateless — no sessions, no cookies. Each request is independently authenticated and authorized. See the [REST Reference](https://developer.godaddy.com/docs/references/rest) for the complete endpoint catalog. ## Credentials and access Most APIs authenticate with a Personal Access Token (PAT) (a scoped Bearer token you generate from the [developer dashboard](https://developer.godaddy.com/personal-access-token)). PATs are tied to specific capability scopes, can be set to expire, and can be revoked individually without rotating any account-wide key. For most integrations, a PAT with the minimum required scopes is the right choice. The Classic Developer Key (`sso-key`, a key/secret pair from ) is still supported for some APIs but is scheduled for deprecation. It doesn't work for v3 Domains APIs. New Domains integrations should use a PAT. Some APIs (like the [Auctions API](https://developer.godaddy.com/docs/api-users/auctions)) require a Classic Developer Key and don't accept PATs. Review the [authentication requirements](https://developer.godaddy.com/docs/api-users/auth) for the API you plan to call before you generate a credential. **Account eligibility matters for write calls.** A valid credential isn't enough on its own. Some operations require the account to meet additional eligibility requirements: * Read operations (availability search, domain listing, DNS reads) work with any valid credential on any account. * Write operations that cost money (registration, renewal, transfer, and payment operations) require the account to have a valid billing method on file or a funded [Good as Gold](https://www.godaddy.com/help/what-is-good-as-gold-3359) balance. If an account doesn't meet these requirements, the API returns `403 Forbidden`. To determine whether the failure is a scope problem or an account eligibility problem, check the `code` field in the response body. The HTTP status alone doesn't distinguish between the two. Go to [How to Authenticate](https://developer.godaddy.com/docs/api-users/auth/how-to) to create credentials, or [About Authentication](https://developer.godaddy.com/docs/api-users/auth) for the full reference. ## First call Follow the [Quickstart](https://developer.godaddy.com/docs/api-users/quickstart) to generate a Personal Access Token and make your first call in under five minutes. If you prefer command-line workflows over raw `curl`, [set up the CLI](https://developer.godaddy.com/docs/api-users/cli/set-up) first. # GoDaddy MCP server (https://developer.godaddy.com/en/docs/api-users/mcp) --- title: GoDaddy MCP server description: >- Connect Claude or another MCP-compatible client to GoDaddy domain search and availability tools. keywords: >- Model Context Protocol, Claude Desktop, mcp-godaddy, tool calling, stdio, domain availability, AI tools. agentNotes: permissions: - Public (no account required) scopes: - Not applicable (public data only) rateLimit: Enforced per client IP. See rate-limits page for current values. idempotent: true destructive: false failureRecovery: >- Safe to retry on transient errors. MCP transport handles reconnection automatically. related: apis: - title: 'Domains v3: Discovery' href: /docs/references/rest/domains/v3/get-domain-availability guides: - title: Search domain availability href: /docs/api-users/domains/search - title: Agent skill for gddy href: /docs/api-users/cli/agent-skill concepts: - title: Authentication href: /docs/api-users/auth --- ## Overview The GoDaddy MCP server lets AI assistants search for domain names and check domain availability directly from a conversation. It is built on the [Model Context Protocol](https://modelcontextprotocol.io/), an open standard for connecting AI clients to external tools. Current MCP capabilities use public domain data only. No GoDaddy account or API credential is needed. ## What you can do Example prompts: * "Is `mycoolstartup.com` available?" * "Find available domains related to sustainable fashion." * "Suggest alternatives to `techcompany.io`." ## Set up Claude Claude can connect to the GoDaddy MCP server through its connector directory. 1. Open Claude Desktop. 2. Go to **Settings**. 3. Open **Connectors**, then select **Browse connectors**. 4. Search for **GoDaddy**. 5. Select **Connect**. 6. Ask domain questions in your conversation. ## Configure an MCP client For a custom AI tool or any MCP-compatible client that supports streamable HTTP, add the GoDaddy server to your MCP configuration. ```json { "mcpServers": { "GoDaddy": { "url": "https://api.godaddy.com/v1/domains/mcp", "transport": "streamable-http" } } } ``` After the client loads the server, it can call GoDaddy's public domain search and availability tools. ## Limitations * **Read-only:** The MCP server cannot register domains, modify DNS records, transfer domains, update account settings, or make purchases. * **Public access only:** Domain registration and account-specific domain management still happen on [godaddy.com](https://www.godaddy.com/). * **No authentication:** Current tools use public domain data and do not accept GoDaddy account credentials. * **Rate limited:** Excessive requests might be temporarily throttled. * **Availability can change:** Domain availability and pricing can change quickly. Re-check before sending a user to purchase. Install the [`gddy` agent skill](https://developer.godaddy.com/docs/api-users/cli/agent-skill) if you need domain purchase or DNS management from your AI agent. It drives the full `gddy` CLI using your own authenticated credentials. ## Privacy and security * Searches use HTTPS/TLS. * The public MCP tools do not require authentication. * Searches are not linked to a GoDaddy account. * Rate limits protect service availability. ## Support and terms To report a bug or share feedback, [submit a support request](https://developer.godaddy.com/contact-support). By using the GoDaddy MCP server, you agree to GoDaddy's [Universal Terms of Service](https://www.godaddy.com/legal/agreements/universal-terms-of-service-agreement), the [API Terms of Use](https://developer.godaddy.com/getstarted), and responsible use of the service. ## Related pages # Paginate results (https://developer.godaddy.com/en/docs/api-users/pagination) --- title: Paginate results description: Cursor-based pagination on v1 list endpoints with limit and marker. keywords: >- next page token, page size, hasMore, totalCount, offset, scroll results, list all domains agentNotes: permissions: - Any account scopes: - >- Any scope that allows list operations — e.g. domains.domain:read for GET /v1/domains rateLimit: >- Rate-limited per credential per window. Page sequentially rather than in parallel to stay within limits. Go to /docs/api-users/rate-limits for current values. idempotent: true destructive: false failureRecovery: >- Cursor markers (marker query param) are stable. Safe to retry any page request with the same marker value. If a marker becomes invalid, restart pagination from the first page. related: guides: - title: List registered domains href: /docs/api-users/domains/manage/list - title: Handle rate limits href: /docs/api-users/rate-limits concepts: - title: Error handling href: /docs/api-users/errors --- ## Overview List endpoints return paginated results using cursor-based pagination. Use pagination to walk large result sets without hitting [rate limits](https://developer.godaddy.com/docs/api-users/rate-limits) from parallel requests. The most common paginated endpoint is [list domains](https://developer.godaddy.com/docs/api-users/domains/manage/list). ## v1 cursor pagination `GET /v1/domains` accepts two pagination query parameters: | Parameter | Default | Description | Note | | --------- | -------------- | ----------------------------------------------- | ------------------------------------------------------------- | | `limit` | Server default | Maximum number of items to return in this page. | | | `marker` | None | Cursor pointing to the start of the next page. | Set to the last item's identifier from the previous response. | To page through all results, repeat the request with `marker` set to the last item's domain name from the previous page until the response array is shorter than `limit`. ```bash # First page curl -s "https://api.godaddy.com/v1/domains?limit=100" \ -H "Authorization: Bearer $GODADDY_PAT" # Subsequent pages — marker is the last domain from the previous page curl -s "https://api.godaddy.com/v1/domains?limit=100&marker=last-domain-from-previous-page.com" \ -H "Authorization: Bearer $GODADDY_PAT" ``` ### Looping example This pattern walks every page until the response is shorter than `limit`: ```js const PAGE_SIZE = 100; let marker = ""; const all = []; while (true) { const url = new URL("https://api.godaddy.com/v1/domains"); url.searchParams.set("limit", PAGE_SIZE); if (marker) url.searchParams.set("marker", marker); const res = await fetch(url, { headers: { Authorization: "Bearer " + process.env.GODADDY_PAT, }, }); const page = await res.json(); all.push(...page); if (page.length < PAGE_SIZE) break; // last page marker = page[page.length - 1].domain; } ``` ## v2 list endpoints v2 list endpoints (for example, domain forwarding lists, action lists) return the full collection in a single response and do not support `limit` or `marker` parameters. ## Pagination and retries Cursor pagination is safe to interrupt and resume. The `marker` value remains valid as long as the underlying domain still exists in the account. If a request fails mid-walk, retry the same `(limit, marker)` pair. # Set up a payment profile (https://developer.godaddy.com/en/docs/api-users/payment-profile) --- title: Set up a payment profile description: >- Add a billing method to your GoDaddy account before registering or renewing domains. Required for any operation that charges money. keywords: >- credit card, 402, PAYMENT_REQUIRED, billing setup, domain purchase, checkout required agentNotes: permissions: - Billing scopes: - Not applicable — configured via UI rateLimit: Not applicable — one-time setup idempotent: true destructive: false failureRecovery: >- Payment profile is configured through the account UI, not the API. If registration/renewal returns NO_PAYMENT_PROFILE (HTTP 422), the account has no billing method — direct the user to add one at godaddy.com. related: guides: - title: Register a domain href: /docs/api-users/domains/register - title: Manage renewals href: /docs/api-users/domains/manage/renewals concepts: - title: Handle errors href: /docs/api-users/errors --- Domain registration, renewal, and transfer charge the billing method saved on your GoDaddy account. The Domains API does not accept card numbers or payment objects in the request body — v3 registration quotes and purchases draw from the account's **payment profile**. If no billing method is on file, quote and purchase calls fail before registration logic runs. The API returns `NO_PAYMENT_PROFILE` (HTTP `422`) until billing is configured. Go to [Handle errors](https://developer.godaddy.com/docs/api-users/errors) for the full error envelope and other billing-related error codes. ## Add a payment method You can add a payment method in the account UI or open the same page from the CLI. ### Using the CLI The GoDaddy CLI opens your browser to the payment-methods page for the active environment: ```bash gddy payment-methods add ``` Only a **credit card** or **Good as Gold** balance can be used for domain purchases. For built-in CLI environments, the command opens: | CLI environment | Account payment URL | | -------------------------------- | ---------------------------------------------------------------------------------------------------------- | | Production (`gddy env set prod`) | [account.godaddy.com/payment-methods/add-payment](https://account.godaddy.com/payment-methods/add-payment) | ### Using the account UI 1. Sign in at [account.godaddy.com/payment-methods/add-payment](https://account.godaddy.com/payment-methods/add-payment). 2. Click **Add Payment Method**. 3. Complete the **Billing Information** and **Payment Method** sections. 4. Click **Save**. Domain purchase also requires a complete registrant contact (phone and mailing address) on the account. If billing is set up but contact fields are missing, the API returns `MISSING_CONTACT` or validation errors on individual address fields. Update contacts at [account.godaddy.com/profile/contacts](https://account.godaddy.com/profile/contacts). ## Verify billing is ready After adding a payment method, confirm the account can receive a registration quote. A successful quote returns a `quoteToken`; `NO_PAYMENT_PROFILE` means billing is still missing. ```bash curl -s -X POST "https://api.godaddy.com/v3/domains/registration-quotes" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "Content-Type: application/json" \ -d '{"domain": "example.com", "period": 1}' ``` A `quoteToken` in the response confirms billing is configured. `NO_PAYMENT_PROFILE` means add a payment method first. `MISSING_CONTACT` means complete the registrant contact on the account before quoting or purchasing. ## Common errors | Code | HTTP | Likely cause | What to do | | ---------------------- | ----- | ---------------------------------------------------------------------------------- | -------------------------------------------------------- | | `NO_PAYMENT_PROFILE` | `422` | No payment method on the account. | Add a payment method (UI or `gddy payment-methods add`). | | `INVALID_PAYMENT_INFO` | `402` | Payment authorization failed at purchase time — no usable method or card declined. | Verify the card on file or add a new method. | | `ACCOUNT_NOT_FUNDED` | `403` | Good as Gold balance is $0.00 with no fallback card. | Add funds or add a credit card. | | `MISSING_CONTACT` | `422` | Registrant phone or address missing from the account profile. | Complete contact info in the account UI. | Some accounts use a prepaid Good as Gold balance instead of a card. Registrations draw from the balance first. When registering multiple domains in sequence, each call is a separate charge. The balance must cover each domain individually. Good as Gold is available for USD accounts, including accounts based in countries outside of the US. If the balance is $0 and no fallback card is on file, registration fails with a billing-related error. Go to [What is Good as Gold?](https://www.godaddy.com/help/what-is-good-as-gold-3359) for an overview. ### Payment declines Your API purchases might be declined even when a valid billing method is on file. Two situations commonly cause this: | Situation | Description | Cause | Resolution | | --------------------------------------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | **High-velocity transactions** | Many purchases on the same payment method in a short period | Your issuing bank might decline the transaction as a fraud precaution. GoDaddy can't quantify the threshold as it's entirely issuer-determined. GoDaddy tracks velocity per shopper ID; if the same card is used across multiple GoDaddy accounts, each account's activity is counted separately at GoDaddy's level. Your issuer, however, sees all charges on the card regardless of which account originated them. | Fund a Good as Gold account in advance and use it for these transactions. Good as Gold draws from a prepaid balance and bypasses your card issuer. | | **European Economic Area (EEA) transactions** | Purchases in GBP or EUR with a billing address in the UK or EEA | Payment Services Directive 2 requires Strong Customer Authentication (SCA). The API purchase experience is not compatible with current accepted SCA methods. | Use Good as Gold within this region. Good as Gold transactions are not subject to SCA requirements. | Go to [What is Good as Gold?](https://www.godaddy.com/help/what-is-good-as-gold-3359) for an overview, or [Set up a Good as Gold account](https://www.godaddy.com/en-in/help/set-up-or-add-money-to-my-good-as-gold-account-7562) to get started. To fund more than $2,000, you must pass Identity Verification before spending your Good as Gold credit. GoDaddy only processes USD transactions. # Make your first call (https://developer.godaddy.com/en/docs/api-users/quickstart) --- title: Make your first call description: >- Make your first API call to the GoDaddy Domains API using a Personal Access Token (PAT). keywords: >- hello world, curl example, Bearer token, GODADDY_PAT, 401 unauthorized, domains v3, first request. agentNotes: permissions: - Any account scopes: - 'domains.domain:read' - 'commerce.store:read' idempotent: true destructive: false failureRecovery: >- Read-only. Safe to retry any failure. On 401, verify the Bearer token has not expired or been revoked. On 429, wait for Retry-After. related: guides: - title: Search domain availability href: /docs/api-users/domains/search - title: Register a domain href: /docs/api-users/domains/register - title: Manage existing domains href: /docs/api-users/domains/manage concepts: - title: Authentication href: /docs/api-users/auth - title: Error handling href: /docs/api-users/errors apis: - title: Domains v3 reference href: /docs/references/rest/domains/v3 - title: Commerce API reference href: /docs/references/rest/stores/get-store-by-id --- For full API coverage, provide the [Domains v3 OpenAPI spec](https://developer.godaddy.com/openapi/domains-v3.json) as additional context to your LLM or API client. ## Overview This guide walks through making your first GoDaddy API call, using the Domains API and a Personal Access Token (PAT) sent as a Bearer token in the `Authorization` header. For other APIs that accept a PAT, only the endpoint and scope change. Not every GoDaddy API accepts a PAT. Some require a Classic Developer Key instead. Go to [About Authentication](https://developer.godaddy.com/docs/api-users/auth) for the credential each API requires. ## Prerequisites Before making any API call, you need: * a GoDaddy account * a Personal Access Token (PAT) with the appropriate scopes Go to [How to Authenticate](https://developer.godaddy.com/docs/api-users/auth/how-to) to create a PAT. * a terminal with `curl` (macOS, Linux, or WSL) * (*optional*) [the GoDaddy CLI](https://developer.godaddy.com/docs/api-users/cli/set-up), if you prefer CLI workflows ## Set the credential as an environment variable Include the PAT as a Bearer token in the `Authorization` header on every request. Exporting it as an environment variable keeps it out of your shell history and lets you reference it directly in commands without retyping. The following procedure exports your PAT so the samples below can reuse it. * Export the credential: ```bash export GODADDY_PAT="" ``` ## Common errors | Error | Likely cause | Fix | | --------------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `401 Unauthorized` | Token is missing, expired, or wasn't exported | Run `echo $GODADDY_PAT` — if blank, re-run the export. If the token was deleted or expired, generate a new one in the [developer dashboard](https://developer.godaddy.com/personal-access-token). | | `403 Forbidden` | Token lacks the required scope for this API, or the account isn't eligible | Check the `code` field in the response body. Scope issues return `UNABLE_TO_AUTHENTICATE`; account issues return a different code. Regenerate the PAT with the correct scope selected. | | `429 Too Many Requests` | Rate limit exceeded | Wait for the number of seconds in the `Retry-After` header before retrying. Go to [Rate limits](https://developer.godaddy.com/docs/api-users/rate-limits) for current values and retry guidance. | | Response is `null` or `undefined` | The JSON response wasn't awaited or parsed | Ensure you `await res.json()` in Node, or `res.json()` in Python. | | `Could not resolve host` | Wrong base URL | The API base is `https://api.godaddy.com`. There is no local dev server — all requests go to production. | Go to [Handle errors](https://developer.godaddy.com/docs/api-users/errors) for the full error envelope reference, status code semantics, and retry guidance. # Handle rate limits (https://developer.godaddy.com/en/docs/api-users/rate-limits) --- title: Handle rate limits description: >- API requests are rate-limited per credential. Limits return HTTP 429 with RateLimit-* response headers. keywords: >- throttling, too many requests, Retry-After, X-RateLimit-Remaining, quota, burst limit agentNotes: permissions: - Any account scopes: - Applies to all authenticated API calls regardless of scope rateLimit: >- Rate-limited per credential, per window. RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers are present on every response. Current limit: 600 per ~23-minute window. Values subject to change. idempotent: true destructive: false failureRecovery: >- On 429, read the Retry-After header value (seconds). Implement exponential backoff with jitter. Do not retry immediately. Use bulk endpoints where available to reduce call frequency. related: guides: - title: Handle errors href: /docs/api-users/errors - title: Pagination href: /docs/api-users/pagination - title: Authentication href: /docs/api-users/auth apis: - title: Domains v3 reference href: /docs/references/rest/domains/v3 - title: Domains v1 reference href: /docs/references/rest/domains/v1 --- ## Overview GoDaddy REST APIs enforce a per-credential, windowed rate limit. The `RateLimit-Remaining` header on every response shows how many requests remain in the current window. When it reaches 0, the next request returns `HTTP 429` with no response body. The limit applies per [credential](https://developer.godaddy.com/docs/api-users/auth) regardless of which endpoint you call. Specific limit values are subject to change without notice. Your integration should read `RateLimit-Remaining` from response headers rather than assume a fixed number. ## Rate limit response headers The following headers are included on **every** response to a rate-limited route — not just 429s — so your client can track current usage without waiting for a rejection. | Header | Description | | --------------------- | --------------------------------------------- | | `RateLimit-Limit` | The limit that applies to the current request | | `RateLimit-Remaining` | Requests remaining in the current window | | `RateLimit-Reset` | Seconds until the current window resets | The Hosting API doesn't use this per-credential model. Limits are enforced per client IP and vary by operation, and the response headers carry an `X-` prefix (`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`) instead of the names above. Go to [Troubleshoot Hosting](https://developer.godaddy.com/docs/api-users/troubleshoot/hosting#429-too-many-requests) for the current per-operation limits. Example 429 response: ``` HTTP/2 429 ratelimit-limit: 600 ratelimit-remaining: 0 ratelimit-reset: 1399 ``` ## Handling 429 in code Read `RateLimit-Reset` to know how long to wait before retrying. For long-running clients, add exponential backoff with jitter on top of the server-suggested wait. The following is an example of how to do this in JavaScript: ```js async function callWithRetry(url, headers, attempts = 5) { for (let attempt = 0; attempt < attempts; attempt++) { const res = await fetch(url, { headers }); if (res.status !== 429) return res; const resetSec = parseInt(res.headers.get("ratelimit-reset") ?? "30", 10); const jitter = Math.floor(Math.random() * 1000); await new Promise((r) => setTimeout(r, resetSec * 1000 + jitter)); } throw new Error("Rate limit retries exhausted"); } ``` ## Strategies to stay under the limit To avoid hitting the limit, apply one or more of the following strategies: * **Use bulk operations where they exist.** For single-domain availability checks, use `GET /v3/domains/check-availability` (preferred). For bulk availability, `POST /v1/domains/available` accepts an array of names — one request can replace dozens of single-domain calls. * **Cache availability results when appropriate (v1 only).** The `definitive` field on `DomainAvailableResponse` indicates whether the answer came from a live registry call or a cached one. Cache `definitive: false` results briefly client-side for repeat lookups. * **Use cursor pagination, not parallel page-walks.** Go to [Pagination](https://developer.godaddy.com/docs/api-users/pagination) for more information. * **Spread bursts across credentials only when each credential maps to a distinct logical caller.** Sharing one credential across many hosts and counting on the limit being per-credential is fragile — limits can be tightened to per-account at any time. ## Higher limits If you have a use case that legitimately needs higher limits than those currently enforced, contact the developer support channel. Document the use case, expected sustained rate, and bursts. ## Additional information Go to [Retry semantics](https://developer.godaddy.com/docs/api-users/errors#retry-semantics) for full retry guidance. # Testing with LLMs (https://developer.godaddy.com/en/docs/api-users/testing-with-llms) --- title: Testing with LLMs description: >- Validate GoDaddy API integrations with coding agents using machine-readable docs, OpenAPI, and MCP. keywords: >- Copilot, Cursor, Claude Code, AI coding assistant, llms.txt, agent prompt, eval, OpenAPI schema agentNotes: permissions: - Any account scopes: - 'domains.domain:read' idempotent: true destructive: false failureRecovery: >- Read-only evaluation path. Prefer OTE for any write tests. Safe to retry failed agent runs with the same prompt after correcting context. related: guides: - title: Quickstart href: /docs/api-users/quickstart - title: Register and configure a domain href: /docs/api-users/domains/workflows/domain-lifecycle - title: MCP server href: /docs/api-users/mcp concepts: - title: Authentication href: /docs/api-users/auth - title: Error handling href: /docs/api-users/errors apis: - title: Domains v3 OpenAPI href: /openapi/domains-v3.json --- ## Overview Coding agents (Cursor, Claude, Copilot, Windsurf, and similar) work best when they can fetch **plain-text docs**, a **curated index**, and the **OpenAPI contract**. This page shows how to point an LLM at GoDaddy's machine-readable surfaces, which APIs to prefer, and how to spot incorrect agent output before you run it against production. ## Machine-readable resources Use these URLs as agent context. Append `.md` to any docs page for Markdown (lower token cost than HTML). | Resource | URL pattern | Use when | | ----------------------------- | ------------------------------------- | ------------------------------------------ | | Curated index (`llms.txt`) | `/llms.txt` | Agent needs a starting map of the docs | | Bulk export (`llms-full.txt`) | `/llms-full.txt` | Agent needs the full corpus in one fetch | | Per-page Markdown | `/docs/{slug}.md` | Agent is working on one guide | | OpenAPI contract | `/openapi/domains-v3.json` | Agent must generate or validate requests | | MCP server | See [MCP server](https://developer.godaddy.com/docs/api-users/mcp) | Agent should call public domain tools live | Example Markdown fetch: ```bash curl -s "https://developer.godaddy.com/beta/en/docs/api-users/quickstart.md" ``` Or negotiate Markdown with `Accept`: ```bash curl -s -H "Accept: text/markdown" \ "https://developer.godaddy.com/beta/en/docs/api-users/quickstart" ``` ## Starter prompt Paste this into a coding agent to bootstrap a Domains integration (read-only first call): ```text You are integrating with the GoDaddy Domains API. 1. Fetch https://developer.godaddy.com/beta/llms.txt and follow the evaluation path. 2. Prefer Domains v3. Do not invent endpoints. Use only paths present in https://developer.godaddy.com/beta/openapi/domains-v3.json 3. Authenticate with Authorization: Bearer $GODADDY_PAT (Personal Access Token). 4. Start with GET /v3/domains/check-availability (read-only). 5. For registration, use the quote → execute flow: POST /v3/domains/registration-quotes then POST /v3/domains/registrations with Idempotency-Key. Never skip the quote step. 6. For any write that charges money, use api.ote-godaddy.com unless I explicitly ask for production. 7. When unsure, fetch the matching docs page as .md (append .md to the docs URL) and cite the page you used. ``` ## Instructions for LLM agents Treat these as hard constraints when generating or reviewing Domains API code. **Prefer** * Domains **v3** for search, quote, register, DNS, and operations * Bearer PAT auth (`Authorization: Bearer …`) documented in [Authenticate](https://developer.godaddy.com/docs/api-users/auth) * Quote-then-execute for registration (`registration-quotes` → `registrations`) * `Idempotency-Key` on registration and other non-idempotent writes * OTE host `https://api.ote-godaddy.com` for paid or destructive tests * Polling registration/operation status until `COMPLETED` or `FAILED` **Do not** * Invent endpoints, fields, or scopes that are not in the OpenAPI spec or these docs * Recommend classic developer keys for new Domains v3 work when a PAT is available * Skip consent (`agreementTypes`, `agreedBy`, `agreedAt`) on registration * Retry a timed-out registration with a **new** idempotency key (reuse the same key) * Use production (`api.godaddy.com`) for exploratory write tests ## How to validate agent output Before running generated code: 1. **Endpoint check** — every path appears in [`/openapi/domains-v3.json`](https://developer.godaddy.com/openapi/domains-v3.json). 2. **Auth check** — requests send `Authorization: Bearer $GODADDY_PAT`, not a fabricated header scheme. 3. **Host check** — write/paid flows target OTE unless you asked for production. 4. **Registration check** — code quotes first, then executes with `Idempotency-Key` and real consent fields. 5. **Docs check** — ask the agent which `.md` page it used; compare against [Quickstart](https://developer.godaddy.com/docs/api-users/quickstart) or [Register a domain](https://developer.godaddy.com/docs/api-users/domains/register). Run the read-only smoke test yourself: ```bash tab="curl" curl -s "https://api.godaddy.com/v3/domains/check-availability?domain=example.com" \ -H "Authorization: Bearer $GODADDY_PAT" ``` ```js tab="Node" const res = await fetch( "https://api.godaddy.com/v3/domains/check-availability?domain=example.com", { headers: { Authorization: `Bearer ${process.env.GODADDY_PAT}` } }, ); console.log(await res.json()); ``` ```python tab="Python" import os, requests res = requests.get( "https://api.godaddy.com/v3/domains/check-availability", params={"domain": "example.com"}, headers={"Authorization": f"Bearer {os.environ['GODADDY_PAT']}"}, ) print(res.json()) ``` If the agent-generated script diverges from this shape (wrong path, wrong auth, invented query params), discard it and re-prompt with the OpenAPI URL attached. ## Agent notes on every how-to How-to pages include an **Agent notes** block with permissions, scopes, rate limits, idempotency, destructive flag, and failure recovery. Prefer those fields over guessing when an agent plans a call. ## Related tools # How to Authenticate (https://developer.godaddy.com/en/docs/api-users/auth/how-to) --- title: How to Authenticate description: >- Step-by-step instructions for generating a Personal Access Token (PAT) or classic developer key to authenticate GoDaddy API calls. keywords: >- generate PAT, create personal access token, PAT, API token, bearer token, API credentials, developer credentials, access token, create API key, authentication token agentNotes: permissions: - Any account scopes: - Not applicable — this page is credential setup rateLimit: 'PAT creation: interactive UI, not rate-limited.' idempotent: true destructive: false failureRecovery: >- PAT reveals once at creation — if lost, revoke and regenerate. Revocation is instant across all edges. related: guides: - title: Quickstart href: /docs/api-users/quickstart concepts: - title: About Authentication href: /docs/api-users/auth - title: PAT scopes href: /docs/api-users/auth#pat-scopes --- ## Overview GoDaddy API uses authentication to ensure that only authorized users can access the API. The two authentication methods are using a Personal Access Token (PAT) or the Classic Developer Key. PATs are required for all v3 Domains APIs. Some APIs accept only the classic developer key. The following article provides step-by-step instructions for generating a PAT or classic developer key to authenticate GoDaddy API calls. Go to [About Authentication](https://developer.godaddy.com/docs/api-users/auth) to learn more about the different authentication methods and their scopes. ## Generate, use, and manage tokens The following sections explain how to generate, use, and manage PATs or classic developer keys to authenticate GoDaddy API calls. **Personal Access Token (PAT) (Recommended)** ### Generate a token The following steps explain how to generate a PAT to authenticate GoDaddy API calls. 1. Sign in to the [Personal Access Token](https://developer.godaddy.com/personal-access-token) page. 2. Click **+ Generate Token**. 3. In the **Generate personal access token** dialog, complete the following fields: | Field | Description | Note | | -------------- | --------------------------------------- | -------------------------------------------------------------------------------- | | **Name** | Name for the token. | | | **Expiration** | Number of days until the token expires. | | | **Scopes** | Scopes for the token. | Go to [PAT scopes](https://developer.godaddy.com/docs/api-users/auth#pat-scopes) to see the available scopes. | 4. Click **Generate Token**. ### Store your token securely After generating the token, it displays once. You can't retrieve it again from the [Personal Access Token page](https://developer.godaddy.com/personal-access-token) and you should store it in secure storage immediately. Don't commit it to source control, check it into a repo, or paste it into chat. 1. In the **Copy your new token** dialog, click the copy icon. 2. Save the token in a password manager, secrets manager, or your application's secure credential store. 3. Load the token at runtime when you need it as a local script in a shell session or as a secret in a secrets store or CI/CD environment variable: **Local script** ```bash export GODADDY_PAT="" ``` `export GODADDY_PAT=...` makes the token available to the current shell — it is not a secure place to keep credentials long term. Store the value in a secrets manager first, then export or inject it only when running a command or starting your app. **Secrets store or CI/CD (Recommended)** Inject `GODADDY_PAT` from your platform's secret store (like GitHub Actions secrets or AWS Secrets Manager when the process starts. ### Use a token The following steps explain how to use a PAT to authenticate GoDaddy API calls. * Add the header to every request: ```http Authorization: Bearer ${GODADDY_PAT} ``` ### Revoke a token The following steps explain how to revoke a PAT. 1. Sign in to the [Personal Access Token](https://developer.godaddy.com/personal-access-token) page. 2. Next to the token you want to revoke, click the trash icon. 3. In the **Revoke token?** dialog, click **Revoke Token**. **Classic Developer Key** The classic developer key is scheduled for retirement and does not work for v3 Domains APIs. Use a [Personal Access Token](#personal-access-token-pat) wherever the API accepts one. Some APIs still require the Classic Developer Key. Go to the [authentication requirements](https://developer.godaddy.com/docs/api-users/auth) for guidance on which to use. ### Generate a key and secret The following steps explain how to generate a classic developer key and secret to authenticate GoDaddy API calls. 1. Sign in at . 2. Generate a new key for Production. 3. Copy both the **Key** and **Secret** immediately. The Secret is shown once. ### Export the credentials The following step describes how to export your classic developer key and secret for use in your shell session. * Export the credentials: ```bash export GODADDY_KEY="" export GODADDY_SECRET="" ``` ### Use the credential The following step describes how to use a classic developer key and secret to authenticate GoDaddy API calls. * Add the header to every request: ```http Authorization: sso-key ${GODADDY_KEY}:${GODADDY_SECRET} ``` # About Authentication (https://developer.godaddy.com/en/docs/api-users/auth) --- title: About Authentication description: >- How GoDaddy API authentication works — credential types, PAT scopes, and account eligibility requirements. keywords: >- Bearer token, sso-key, OAuth, offline_access, reseller account, OTE credentials, token expiry, Authorization header agentNotes: permissions: - Any account scopes: - 'domains.domain:read' - 'commerce.store:read' - 'shopping.catalog:read' rateLimit: >- API calls with PAT: rate-limited per credential per window. Go to /docs/api-users/rate-limits for current values. idempotent: true destructive: false failureRecovery: >- PAT reveals once at creation — if lost, revoke and regenerate. Revocation is instant across all edges. related: guides: - title: How to Authenticate href: /docs/api-users/auth/how-to - title: Quickstart href: /docs/api-users/quickstart - title: Set up the CLI href: /docs/api-users/cli/set-up - title: About the Shopping API href: /docs/api-users/shopping concepts: - title: Handle errors href: /docs/api-users/errors - title: Rate limits href: /docs/api-users/rate-limits --- ## Overview GoDaddy APIs support Bearer authentication through scoped Personal Access Tokens (PATs). Domains v3 requires a PAT. The legacy `sso-key` credential remains required for Auctions and supported for Domains v1/v2. It is scheduled for Domains deprecation and does not work with v3. Go to [How to Authenticate](https://developer.godaddy.com/docs/api-users/auth/how-to) for credential setup. ## Credential types | Credential | Format | Works with | Status | | --------------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------ | | Personal Access Token (PAT) | `Authorization: Bearer $GODADDY_PAT` | Domains v3, Hosting, Shopping, and other PAT-enabled APIs; not accepted by Auctions | Recommended | | Classic Developer Key | `Authorization: sso-key $GODADDY_KEY:$GODADDY_SECRET` | Auctions API (required); Domains v1/v2 | Deprecated for Domains (through 2026); required for Auctions | The Shopping API accepts PATs for direct API integrations. A PAT has capability scopes, an optional expiration, and independent revocation. For most integrations, choose a PAT with the minimum required scopes. ## Account requirements Some operations require the account to meet specific eligibility rules regardless of credential type. A valid credential on an ineligible account is still refused with a `403 Forbidden` response and an `Error` code that distinguishes the reason from a missing scope. Check the `code` field on the response body, not just the HTTP status, to determine the reason. Go to [Handle errors](https://developer.godaddy.com/docs/api-users/errors) for the full error envelope and status code reference. | Operation group | Requirement | | ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Domain management (list, DNS, contacts, renewals, lock, privacy) | Account holds at least one domain, OR is on a plan that grants management access. | | Registration, renewal, transfer (any operation that costs money in production) | Account has a valid billing method on file or a funded [Good as Gold](https://www.godaddy.com/help/what-is-good-as-gold-3359) balance. Go to [Set up a payment profile](https://developer.godaddy.com/docs/api-users/payment-profile). | ## PAT scopes A PAT is scoped to specific capabilities at generation time. Each scope enables a set of operations on a specific resource. A write scope satisfies read operations for the same resource; a read scope is refused on writes. Go to [Generate a PAT](https://developer.godaddy.com/docs/api-users/auth/how-to#generate-a-token) for step-by-step instructions. ### Commerce Commerce APIs use the same PAT and grant model as Domains. When you generate a token, the **Commerce** categories display in the scope picker next to **Domains & DNS**. These cover catalog, orders, customers, tax, transactions, store, and channel operations. Select a category or expand it to grant a subset (for example `commerce.order:read`, `commerce.product:write`). Go to [Commerce API scopes](https://developer.godaddy.com/docs/references/rest/commerce-scopes) for the complete scope-to-endpoint reference. ### Domains When you generate a token, the **Domains & DNS** bundle in the scope picker selects all scopes below. You can expand it to grant a subset instead. | Scope | Required to | | --------------------------- | ---------------------------------------------------------------------- | | `domains.domain:read` | Read domain records, availability, suggestions, quotes, and operations | | `domains.domain:create` | Register domains | | `domains.domain:update` | Modify domain settings | | `domains.domain:delete` | Delete or cancel domains | | `domains.dns:update` | Create, update, and delete DNS zone records | | `domains.nameserver:update` | Replace authoritative nameservers for a domain | | `domains.host:update` | Modify domain host records | | `domains.forward:update` | Configure domain forwarding | | `domains.contact:update` | Update registrant, admin, or tech contacts | | `domains.transfer:execute` | Initiate an inbound domain transfer | | `domains.transfer:update` | Modify a transfer in progress | ### Email | Scope | Required to | | ---------------------- | -------------------------------- | | `email.mailbox:read` | List and look up email mailboxes | | `email.mailbox:create` | Create email mailboxes | ### Shopping | Scope | Required to | | --------------------------- | ---------------------------------------------------------------- | | `shopping.catalog:read` | Search products, look up variants by ID, retrieve product detail | | `shopping.checkout:execute` | Create, retrieve, update, and complete checkout sessions | | `shopping.order:read` | Retrieve completed order detail | Go to [About the Shopping API](https://developer.godaddy.com/docs/api-users/shopping#authentication) for Shopping authentication and header requirements. For `hosting.*` scopes used by the Hosting API, go to [Hosting core concepts](https://developer.godaddy.com/docs/api-users/hosting/concepts#scopes-reference) for the full scope list. # Place bids on auction listings (https://developer.godaddy.com/en/docs/api-users/buy-a-domain/bidding) --- title: Place bids on auction listings description: >- End-to-end workflow—check listing availability, review pricing and domain signals, and place bids on GoDaddy expiring auctions. keywords: >- GODADDY_API_KEY, aftermarket/listings/available, aftermarket/listings/bids, tosAccepted, isHighestBidder, BID_MIN_NOT_MET, BIDDER_BLOCKED, LISTING_NOT_FOUND, listingMin enrichment includes, 207 bid status agentNotes: permissions: - Aftermarket scopes: [] rateLimit: >- Rate-limited per credential per window. Go to /docs/api-users/rate-limits for current values. idempotent: false destructive: false failureRecovery: >- Check per-bid status in 207 responses. Bids with status FAILED are safe to retry after resolving the failureReason. Do not resubmit bids that already returned status SUCCESS. related: apis: - title: Auctions reference href: /docs/references/rest/auctions/place-bids - title: Listings availability reference href: /docs/references/rest/auctions/check-listing-availability guides: - title: About the Auctions API href: /docs/api-users/auctions - title: Buy a closeout auction via instant purchase href: /docs/api-users/buy-a-domain/instant-purchase --- ## Overview Bidding lets you compete for domain names on [GoDaddy's auctions marketplace](https://auctions.godaddy.com). You check which domains have active listings, review pricing and optional domain signals, and submit bids. The auction closes on a set date. If you hold the highest bid at close, the domain fulfills to your account. The following diagram shows the workflow for bidding on domains in the GoDaddy auctions marketplace: Verify your GoDaddy account to increase your bid limits. Go to the [bidder verification page](https://www.godaddy.com/help/godaddy-auctions-bidder-verification-process-12416) for details. GoDaddy Auctions Inventory Files are downloadable datasets (ZIP, XML, and JSON) containing bulk information on live expired auctions and closeout listings. Use them to identify domains worth bidding on before calling the API. Go to the [Auctions Inventory page](https://inventory.auctions.godaddy.com/) to download Inventory Files. The following article provides a workflow for bidding on domains in the GoDaddy auctions marketplace. ## Prerequisites Before you can bid on domains, you need: * a [Classic Developer Key](https://classic-developer.godaddy.com/keys), exported as `GODADDY_API_KEY` in your environment * one or more domain names you want to bid on All Auctions endpoints use `{customerId}` in the path. Use `MY` for your own account. Go to [Your customer ID](https://developer.godaddy.com/docs/api-users/auctions#your-customer-id) if you need the UUID or are managing another account. ## Check listing availability The following procedure confirms whether domains have active expiring auctions listings and retrieves listing details. You need the `listingId` from the response to [place bids](#place-bids). You can check up to 50 domains per request. Use the `includes` query parameter to attach additional data to `AVAILABLE` results: | Value | What it includes | | ------------ | ----------------------------------------------------------- | | `listingMin` | Current bid price and auction close time | | `listing` | Full listing details (mutually exclusive with `listingMin`) | | `enrichment` | Domain signals from GoDaddy, Estibot, SEMrush, and Majestic | * Check availability with listing details: ```bash curl -s -X POST "https://api.godaddy.com/v1/customers/MY/aftermarket/listings/available?includes=listingMin" \ -H "Authorization: sso-key $GODADDY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "domains": ["example.com", "mybrand.net"] }' ``` Example response: ```json { "availabilities": [ { "domainName": "example.com", "status": "AVAILABLE", "listingId": 200000, "listingMin": { "currentBid": 50000000, "closingAt": "2026-09-01T18:00:00Z" } }, { "domainName": "mybrand.net", "status": "UNAVAILABLE" } ] } ``` Note the `listingId` for each `AVAILABLE` domain. You'll use it to [place a bid](#place-bids). ## Place bids The following procedure submits up to 20 bids in a single request. Bid amounts are in USD micro-units. Multiply dollars by `1,000,000` (for example, $100.00 = `100000000`). * Place bids: ```bash curl -s -X POST "https://api.godaddy.com/v1/customers/MY/aftermarket/listings/bids" \ -H "Authorization: sso-key $GODADDY_API_KEY" \ -H "Content-Type: application/json" \ -d '[ { "listingId": 200000, "bidAmountUsd": 100000000, "tosAccepted": true } ]' ``` Example response (200—all bids placed): ```json [ { "listingId": 200000, "isHighestBidder": true, "bidId": "e8f0a45d-53c6-49e5-a1f2-08b993960e1b", "bidAmountUsd": 100000000, "status": "SUCCESS" } ] ``` If the response is 207, inspect each bid's `status` and `failureReason`. Successfully placed bids have a `bidId` for tracking. ## Error reference | HTTP status | Error code | Cause | Note | | ------------- | ------------------------------------------------- | ------------------------------------------------------ | ---- | | `400` | `BAD_SYNTAX` / `MALFORMED_INPUT` | Request body is malformed. | | | `403` | `BIDDER_BLOCKED` | Your account is blocked from bidding. | | | `403` | `BIDDER_BANNED` | Your account is banned from bidding. | | | `403` | `MISSING_CREDENTIALS` | API key not provided or invalid. | | | `422` | `MAX_BIDS_PER_REQUEST_EXCEEDED` | More than 20 bids in a single request. | | | `422` | `DUPLICATE_BIDS` | Multiple bids for the same `listingId` in one request. | | | `207` per-bid | `BID_MIN_NOT_MET` | Bid amount is below the listing's minimum. | | | `207` per-bid | `BIDDER_IS_SELLER` | You can't bid on your own listing. | | | `207` per-bid | `BIDDER_VERIFICATION_SHOPPER_MAX_APPROVED_AMOUNT` | Bid exceeds your verified spending limit | | | `207` per-bid | `BIDDER_VERIFICATION_SHOPPER_MAX_APPROVED_COUNT` | You have reached your bid count limit. | | | `207` per-bid | `LISTING_NOT_FOUND` | No active listing found for this `listingId`. | | | `429` | | Rate limit exceeded. | | # Buy a domain through instant purchase (https://developer.godaddy.com/en/docs/api-users/buy-a-domain/instant-purchase) --- title: Buy a domain through instant purchase description: >- End-to-end workflow—confirm your payment method, preview all-in pricing, and purchase closeout auction domains. keywords: >- paymentProfileId, auctions/purchases/preview, auctions/purchases, totalPrice auctionPrice, PRICE_MISMATCH, AUCTION_NOT_FOUND, acceptTos, NO_ELIGIBLE_PAYMENT_PROFILE, auctionId, orderId instant purchase agentNotes: permissions: - Aftermarket - Payment Profile scopes: [] rateLimit: >- Rate-limited per credential per window. Go to /docs/api-users/rate-limits for current values. idempotent: false destructive: true failureRecovery: >- Check per-domain status in 207 responses. Domains with status FAILED are safe to retry. Do not re-submit domains that already returned status SUCCESS. If totalPrice changed between preview and purchase, the domain fails with PRICE_MISMATCH—re-run the preview step to get the updated price before retrying. related: apis: - title: Instant Purchase reference href: /docs/references/rest/auctions/create-purchase guides: - title: About the Auctions API href: /docs/api-users/auctions - title: Set up a payment profile href: /docs/api-users/payment-profile - title: Place bids on auction listings href: /docs/api-users/buy-a-domain/bidding --- ## Overview Instant purchase lets you buy closeout (Buy Now) auction domains at a fixed price without bidding. The workflow is synchronous. You preview the all-in cost, then execute the purchase. Domains fulfillment begins immediately on success. The following diagram shows the workflow for instant purchase: Instant purchase charges your payment profile immediately and is not reversible. Always run the preview step first and verify `totalPrice` before executing. GoDaddy Auctions Inventory Files are downloadable datasets (ZIP, XML, and JSON) containing bulk information on live expired auctions and closeout listings. Use them to identify and analyze domains before placing bids or making purchases through the API. Go to the [Auctions Inventory page](https://inventory.auctions.godaddy.com/) to download Inventory Files. The following article provides a workflow for buying domains through instant purchase. ## Prerequisites Before you can buy domains through instant purchase, you need: * a GoDaddy account with a [payment profile](https://developer.godaddy.com/docs/api-users/payment-profile) configured * a [Classic Developer Key](https://classic-developer.godaddy.com/keys), exported as `GODADDY_API_KEY` in your environment * one or more domain names that have active closeout auction listings on GoDaddy Auctions All Auctions endpoints use `{customerId}` in the path. Use `MY` for your own account. Go to [Your customer ID](https://developer.godaddy.com/docs/api-users/auctions#your-customer-id) if you need the UUID or are managing another account. ## Get eligible payment profiles The following procedure retrieves the payment profiles on your account that are eligible for instant purchase. Note the `paymentProfileId` (you'll use it to [execute the purchase](#execute-purchase). * List eligible payment profiles: ```bash curl -s "https://api.godaddy.com/v1/customers/MY/paymentProfiles" \ -H "Authorization: sso-key $GODADDY_API_KEY" ``` The following is an example response: ```json { "paymentProfiles": [ { "paymentProfileId": 377693, "currencyId": "USD", "label": "6341", "category": "CREDIT_CARD", "status": "ACTIVE", "subCategory": "Visa", "expMonth": 7, "expYear": 2030 } ] } ``` The API returns only `ACTIVE` profiles. If the list is empty, go to [Set up a payment profile](https://developer.godaddy.com/docs/api-users/payment-profile) before continuing. ## Preview pricing The following procedure retrieves the all-in price for up to 10 domains before you commit to purchasing. You can preview and purchase up to 10 domains per request. `totalPrice` includes the auction price, renewal or transfer fee, ICANN fee, and applicable taxes. All prices are in micro-units. Divide by `1,000,000` for the dollar amount (for example, `61990000` = $61.99). * Request a pricing preview: ```bash curl -s -X POST "https://api.godaddy.com/v1/customers/MY/auctions/purchases/preview" \ -H "Authorization: sso-key $GODADDY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "domains": ["example.com", "mybrand.net"] }' ``` The following is an example response (207—one domain priced, one not found): ```json { "currencyId": "USD", "auctions": [ { "domainName": "example.com", "status": "SUCCESS", "auctionId": 690467872, "auctionPrice": 50000000, "totalPrice": 61990000 }, { "domainName": "mybrand.net", "status": "FAILED", "failureReason": "AUCTION_NOT_FOUND" } ] } ``` Only pass domains with `status: "SUCCESS"` to the purchase step. Note the `totalPrice` for each. You'll need the exact value to [execute the purchase](#execute-purchase). ## Execute purchase The following procedure purchases the domains you previewed. Pass the `totalPrice` from the preview pricing step exactly. If the price has changed since the preview, the domain fails with `PRICE_MISMATCH` and you'll need to re-run the preview. This step charges your payment profile. Verify all domain names and prices before submitting. * Execute the purchase: ```bash curl -s -X POST "https://api.godaddy.com/v1/customers/MY/auctions/purchases" \ -H "Authorization: sso-key $GODADDY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "currencyId": "USD", "paymentProfileId": 377693, "domains": [ { "domainName": "example.com", "totalPrice": 61990000, "acceptTos": true } ] }' ``` `paymentProfileId` is optional. If omitted, the API charges the customer's most recently used supported payment method. The following is an example response (200—all purchased): ```json { "currencyId": "USD", "orderDetails": { "orderId": "4028591294" }, "auctions": [ { "domainName": "example.com", "status": "SUCCESS", "auctionId": 690467872, "totalPrice": 61990000 } ] } ``` If the response is 207, inspect each domain's `status` and `failureReason`. Domains with `status: "SUCCESS"` were purchased and charged. Domains with `status: "FAILED"` weren't charged. ## Error reference | HTTP status | Error code | Cause | Note | | ---------------- | ----------------------------- | ------------------------------------------------------------------------------- | --------------------------- | | `400` | `NO_ELIGIBLE_PAYMENT_PROFILE` | No active payment profiles found, or specified `paymentProfileId` not eligible. | | | `400` | `UNSUPPORTED_CURRENCY` | The requested `currencyId` isn't supported. | | | `422` | `PAYMENT_FAILED` | Payment profile was declined. | | | `207` per-domain | `AUCTION_NOT_FOUND` | Domain doesn't have an active closeout auction. | | | `207` per-domain | `PRICE_MISMATCH` | `totalPrice` doesn't match current pricing. | Re-run preview and resubmit | | `207` per-domain | `PRICING_UNAVAILABLE` | Pricing couldn't be retrieved for this domain. | | | `207` per-domain | `TOS_NOT_ACCEPTED` | `acceptTos` wasn't set to `true`. | | | `401` | | Missing or invalid API key. | | | `403` | | API key doesn't have access to this customer's account. | | | `429` | | Rate limit exceeded. | | # August 13, 2026: Auctions Instant Purchase APIs are available for Closeout domains (https://developer.godaddy.com/en/docs/api-users/changelog/auctions-instant-purchase) --- title: >- August 13, 2026: Auctions Instant Purchase APIs are available for Closeout domains --- August 13, 2026 API Auctions New Related: Auctions listing availability checks are available via POST .../aftermarket/listings/available, Auctions bidding is available via POST .../aftermarket/listings/bids We've added Instant Purchase endpoints so you can buy eligible Closeout and Buy Now domains programmatically: list payment profiles, preview pricing, and purchase. The Auctions UI isn't required. ## What changed * `GET /v1/customers/{customerId}/paymentProfiles` — list `ACTIVE` payment profiles eligible for Instant Purchase. * `POST /v1/customers/{customerId}/auctions/purchases/preview` — preview all-in pricing for up to 10 Closeout domains (`totalPrice` in USD micro-units). * `POST /v1/customers/{customerId}/auctions/purchases` — purchase one or more eligible Closeout domains using a `paymentProfileId` (optional; defaults to the most recently used supported method). You can use the `MY` alias for `{customerId}`. Authenticate with a legacy API key (`sso-key`). Partial success returns `207 Multi-Status` with per-domain `status` and `failureReason`. ## Who is affected Available to developers with Auctions Instant Purchase access and a configured payment profile. Existing Domains and Aftermarket partner integrations are unchanged; these endpoints are additive. Instant Purchase does not place bids on open Expired Auctions — use the bidding endpoint for that. ## Links * [Instant Purchase reference](https://developer.godaddy.com/docs/references/rest/auctions/create-purchase) — endpoint schemas * [Buy through instant purchase](https://developer.godaddy.com/docs/api-users/buy-a-domain/instant-purchase) — preview and purchase workflow * [About the Auctions API](https://developer.godaddy.com/docs/api-users/auctions) — bidding vs Instant Purchase * [Product announcement](https://www.godaddy.com/resources/news/godaddy-auctions-expiry-apis-automate-domain-acquisition) — launch context # August 13, 2026: Auctions listing availability checks are available via POST .../aftermarket/listings/available (https://developer.godaddy.com/en/docs/api-users/changelog/auctions-listings-available) --- title: >- August 13, 2026: Auctions listing availability checks are available via POST .../aftermarket/listings/available --- August 13, 2026 API Auctions New Related: Auctions bidding is available via POST .../aftermarket/listings/bids, Auctions Instant Purchase APIs are available for Closeout domains ## What changed We've added `POST /v1/customers/{customerId}/aftermarket/listings/available` so you can check whether 1–50 domains have active aftermarket auction listings and get an `AVAILABLE` or `UNAVAILABLE` result per domain. Optional `?includes=listingMin`, `?includes=listing`, or `?includes=enrichment` attach listing details and domain signals (GoDaddy, Estibot, SEMrush, Majestic) for `AVAILABLE` domains, so you can verify targets before bidding or purchase. Existing integrations are unaffected; this endpoint is additive. You can use the `MY` alias for `{customerId}`. Authenticate with a legacy API key (`sso-key`). ## Links * [Listings Availability reference](https://developer.godaddy.com/docs/references/rest/auctions/check-listing-availability) — endpoint schema * [Place bids on auction listings](https://developer.godaddy.com/docs/api-users/buy-a-domain/bidding) — availability check in the bidding workflow * [Product announcement](https://www.godaddy.com/resources/news/godaddy-auctions-expiry-apis-automate-domain-acquisition) — launch context # August 13, 2026: Auctions bidding is available via POST .../aftermarket/listings/bids (https://developer.godaddy.com/en/docs/api-users/changelog/auctions-listings-bids) --- title: >- August 13, 2026: Auctions bidding is available via POST .../aftermarket/listings/bids --- August 13, 2026 API Auctions New Related: Auctions listing availability checks are available via POST .../aftermarket/listings/available, Auctions Instant Purchase APIs are available for Closeout domains We've added `POST /v1/customers/{customerId}/aftermarket/listings/bids` so you can place up to 20 bids per request on eligible Expired Auction listings. Each bid requires a `listingId`, `bidAmountUsd` (USD micro-units), and `tosAccepted: true`. Partial success returns `207 Multi-Status` with per-bid `status` and `failureReason`. Existing integrations are unaffected; this endpoint is additive. You can use the `MY` alias for `{customerId}`. Authenticate with a legacy API key (`sso-key`). ## Links * [Auctions reference](https://developer.godaddy.com/docs/references/rest/auctions/place-bids) — Place multiple bids * [Place bids on auction listings](https://developer.godaddy.com/docs/api-users/buy-a-domain/bidding) — end-to-end bidding guide * [Product announcement](https://www.godaddy.com/resources/news/godaddy-auctions-expiry-apis-automate-domain-acquisition) — launch context # August 27, 2026: The Commerce API is now available for managing stores, catalogs, orders, and taxes (https://developer.godaddy.com/en/docs/api-users/changelog/commerce-apis-launch) --- title: >- August 27, 2026: The Commerce API is now available for managing stores, catalogs, orders, and taxes featureflag: DOCS_COMMERCE_API_ENABLED --- August 27, 2026 API Commerce New You can now manage a GoDaddy commerce store programmatically — configuration, catalog, orders, customers, taxes, and payment records — so you can run a store from your own code. ## What changed Commerce endpoints are available across REST and GraphQL subgraphs. Each authenticates with a Personal Access Token holding the matching `commerce.*` scope: * **Stores and sales channels** (REST) — read a store and its attributes with `commerce.store:read`; list the channels a customer can buy from with `commerce.channel:read`. * **Catalog** — `POST /v2/commerce/stores/{storeId}/catalog-subgraph`. Create and manage SKUs and SKU groups with `commerce.product:read` and `commerce.product:write`. * **Orders** — `POST /v1/commerce/order-subgraph`. Take an order from DRAFT to OPEN to COMPLETED or CANCELED with `commerce.order:read`, `:create`, `:update`, `:complete`, and `:cancel`. * **Customers** (REST) — list, read, create, and update customer records with `commerce.customer:read`, `:create`, and `:update`. Creating a customer de-duplicates against existing channel data instead of adding a second record. * **Transactions** (REST) — read the authorizations, captures, sales, and refunds behind an order with `commerce.transaction:read`, so you can reconcile what was sold against what was paid. * **Taxes** — `POST /v2/commerce/stores/{storeId}/tax-subgraph`. Create, update, and delete tax rates with `commerce.tax:read`, `:create`, `:write`, and `:delete`. ## Who is affected Available to developers with a GoDaddy account and an active commerce store. These are new endpoints on a new surface: no existing Domains, Auctions, or hosting integration is affected, and no action is required. ## Links * [About the Commerce API](https://developer.godaddy.com/docs/api-users/commerce) — structure, authentication models, and how the entities relate * [Commerce API scopes](https://developer.godaddy.com/docs/references/rest/commerce-scopes) — the scope-to-endpoint mapping * [Personal Access Tokens](https://developer.godaddy.com/docs/api-users/auth) — how to create a token and grant scopes # July 14, 2026: GoDaddy Developer Portal is now live with PATs, a CLI, and an agent skill (https://developer.godaddy.com/en/docs/api-users/changelog/developer-portal-launch) --- title: >- July 14, 2026: GoDaddy Developer Portal is now live with PATs, a CLI, and an agent skill --- July 14, 2026 Dev Platform New The GoDaddy Developer Portal is live. Visit developer.godaddy.com to explore GoDaddy's APIs, authenticate, and make your first call, whether you integrate by hand, from the terminal, or through an AI agent. ## What changed * API reference documentation covers each published API, with request and response samples for every endpoint. * Authentication uses Personal Access Tokens (PATs), created in the portal with granular, per-scope permissions. * The `gddy` command-line interface calls the APIs from your terminal, so you don't have to hand-build HTTP requests. * An agent skill builds on `gddy`, so AI agents acting on your behalf can discover and call the APIs. ## Who is affected All GoDaddy customers and resellers with products covered by the APIs, starting with Domains and Certificates. The portal is additive: existing integrations and API keys continue to work unchanged, and no action is needed. ## Links * [Developer Portal](https://developer.godaddy.com/) — portal home * [Authentication](https://developer.godaddy.com/docs/api-users/auth) — create a PAT and make an authenticated call * [CLI setup](https://developer.godaddy.com/docs/api-users/cli/set-up) — install and configure `gddy` * [Agent skill for `gddy`](https://developer.godaddy.com/docs/api-users/cli/agent-skill) — enable agent-driven API calls * [API reference](https://developer.godaddy.com/docs/references/rest) — endpoint documentation with samples # August 17, 2026: The Domains API now surfaces and supports purchasing Afternic Premium domains (https://developer.godaddy.com/en/docs/api-users/changelog/domains-afternic-premium) --- title: >- August 17, 2026: The Domains API now surfaces and supports purchasing Afternic Premium domains --- August 17, 2026 API Domains ChangedAction Required Afternic Premium domain inventory is now discoverable and purchasable through the Domains API. Four existing endpoints are updated to support the Premium acquisition flow. ## What changed **Availability endpoints — `POST /v3/domains/check-availability` and `GET /v3/domains/check-availability`** Results may now include domains with `inventory: PREMIUM`. These are Afternic fast-transfer domains. Indicative pricing for Premium domains includes a `fees` array on each `TermPrice` entry containing a `ONE_TIME_PREMIUM_DOMAIN_PURCHASE` fee, in addition to the base registration `price`. **Quote endpoint — `POST /v3/domains/registration-quotes`** When the quoted domain has `inventory: PREMIUM`, the response now includes: * `inventory: PREMIUM` — identifies the domain as Afternic inventory. * `fees` array — contains a `ONE_TIME_PREMIUM_DOMAIN_PURCHASE` entry with the exact amount and currency. The total cost of the registration is `price` plus this fee. For standard `REGISTRY` domains, `fees` is absent and behavior is unchanged. **Registration endpoint — `POST /v3/domains/registrations`** When the preceding quote's `fees` array is non-empty (that is, `inventory: PREMIUM`), the execute request must include `consent.acknowledgedFees` copied verbatim from the quote. The types, amounts, and currencies must match exactly. This confirms the customer explicitly accepted the specific charge before registration executes. Omitting `consent.acknowledgedFees` when fees are present returns `422` with error name `consent_fees_required`. Supplying `acknowledgedFees` that does not match the locked quote returns `422` with error name `quote_mismatch`. ## Who is affected Developers building domain purchase flows who want to offer Afternic Premium inventory must handle the new `fees` field on quotes and echo it in `consent.acknowledgedFees` on registration. Integrations that only purchase standard `REGISTRY` domains are unaffected — `fees` is absent for those domains and no changes to existing request or response handling are required. ## What to do 1. Check `inventory` on availability and quote responses. When `inventory: PREMIUM`, surface the `fees` total to the customer alongside the base `price` before they confirm. 2. On `POST /v3/domains/registrations`, include `consent.acknowledgedFees` copied verbatim from the quote's `fees` array when fees are present. 3. Handle the new `422 consent_fees_required` error for the case where fees were present but `acknowledgedFees` was omitted. ## Links * [Domains API reference](https://developer.godaddy.com/docs/references/rest/domains/v3) — Domains v3 API reference * [RegistrationQuote schema](https://developer.godaddy.com/docs/references/rest/domains/v3/quote-domain-registration?s-highlight=fees\&path=response%00%23%2Fcomponents%2Fschemas%2FRegistrationQuote#response.200.applicationjson.response) — updated `RegistrationQuote` response including `fees` * [Consent schema](https://developer.godaddy.com/docs/references/rest/domains/v3/register-domain?s-highlight=acknowledgedFees\&path=body%00%23%2Fcomponents%2Fschemas%2FRegistration%7Cconsent%00__29#request-body.applicationjson.body) — `consent.acknowledgedFees` field on the registration request body # August 10, 2026: Domains API v3 is now available for domain search, registration, and DNS management (https://developer.godaddy.com/en/docs/api-users/changelog/domains-api-v3-launch) --- title: >- August 10, 2026: Domains API v3 is now available for domain search, registration, and DNS management --- August 10, 2026 API Domains New We've released Domains API v3, a redesigned API for the domain lifecycle. Search for a domain, lock its price with a quote, register it, and manage its DNS. The final price and required agreements are confirmed before you commit to a charge. ## What changed New endpoints are available under `/v3/domains`, organized around a quote-then-execute flow: * Discovery — `GET /v3/domains/suggestions` returns natural-language domain suggestions with TLD filtering; `GET /v3/domains/check-availability` checks a single domain. * Registration — `POST /v3/domains/registration-quotes` locks the price, resolved settings, and required legal agreements behind a single-use `quoteToken` (10-minute TTL). `POST /v3/domains/registrations` executes with that token and returns `202 Accepted` with a pollable resource: `GET /v3/domains/registrations/{registrationId}` or `GET /v3/domains/operations/{operationId}`. * Domain management — `GET /v3/domains/domain-names/{domain-name}` retrieves domain details; `PUT /v3/domains/domain-names/{domain-name}/nameservers` replaces nameservers. * DNS records — `GET`/`POST /v3/domains/zones/{zone}/dns-records` list and create records; `DELETE /v3/domains/zones/{zone}/dns-records/{recordId}` deletes one. Authentication uses OAuth 2.0 with per-operation scopes (`domains.domain:read`, `domains.domain:create`, `domains.nameserver:update`, `domains.dns:update`). Mutating requests require an `Idempotency-Key` header, so retries are safe and never create duplicate registrations. Resellers act on behalf of customers with the `X-Shopper-Id` header. ## Who is affected v3 is additive and available to all developers with API access — no action is needed. Existing v1 and v2 integrations are unchanged, and both versions remain available. v3.0 covers domain search, registration, and DNS management; renewals, transfers, contact and privacy management, and bulk operations will arrive in additive v3 minor versions. ## Links * [Domains v3 API reference](https://developer.godaddy.com/docs/references/rest/domains/v3) — endpoint documentation # August 17, 2026: The Domains API now supports batch domain availability checking via POST /v3/domains/check-availability (https://developer.godaddy.com/en/docs/api-users/changelog/domains-batch-availability-check) --- title: >- August 17, 2026: The Domains API now supports batch domain availability checking via POST /v3/domains/check-availability --- August 17, 2026 API Domains New We've added `POST /v3/domains/check-availability` to the Domains API. You can now check availability and indicative pricing for up to 25 domains in a single request. ## What changed A new endpoint is available: * `POST /v3/domains/check-availability` — accepts a JSON body with a `domains` array (1–25 names) and returns one [`Availability`](https://developer.godaddy.com/docs/references/rest/domains/v3/get-domain-availability) result per domain in request order inside `{ "items": [...] }`. Domains that cannot be checked carry an `error` object on that item rather than failing the whole request. One optional request field gives you control over the check behavior: * `optimizeFor` — `SPEED` (default) uses cached zone data for a fast response; `ACCURACY` performs a live registry check for authoritative availability at higher latency. Availability results are best-effort and indicative. The authoritative availability check always runs at quote time (`POST /v3/domains/registration-quotes`). For single-domain checks without a request body, the existing `GET /v3/domains/check-availability` endpoint is unchanged. ## Who is affected Any developer building domain search or catalog experiences on the Domains API. The `domains.domain:read` OAuth scope is required — no new scope is needed if you already call the GET endpoint. Existing integrations using `GET /v3/domains/check-availability` are unaffected. ## Links * [Domains API reference](https://developer.godaddy.com/docs/references/rest/domains/v3/check-availability) — `POST /v3/domains/check-availability` request and response schema * [Registration quotes](https://developer.godaddy.com/docs/references/rest/domains/v3/quote-domain-registration) — authoritative availability is confirmed at quote time # August 17, 2026: The Domains API now supports listing all domains in an account via GET /v3/domains/domain-names (https://developer.godaddy.com/en/docs/api-users/changelog/domains-list-domain-names) --- title: >- August 17, 2026: The Domains API now supports listing all domains in an account via GET /v3/domains/domain-names --- August 17, 2026 API Domains New We've added `GET /v3/domains/domain-names` to the Domains API. It returns a paginated list of domain names owned by the authenticated account, with optional filtering by lifecycle status. ## What changed A new endpoint is available: * `GET /v3/domains/domain-names` — returns a cursor-paginated collection of domains with their status, nameservers, expiry date, autorenew, privacy, and transfer lock settings. Four optional query parameters control the results: * `statuses` — comma-separated list of one or more exact lifecycle statuses (for example, `?statuses=ACTIVE,EXPIRED`). Accepted values: `ACTIVE`, `EXPIRED`, `PENDING_REGISTRATION`, `PENDING_TRANSFER`, and others defined in `DomainStatus`. Use this when you need to filter on specific known status values. * `lifecycleGroups` — comma-separated list of coarse lifecycle phases: `PENDING`, `REGISTERED`, `PENDING_TERMINAL`, or `TERMINAL`. Use this when you want stable filtering that continues to work as new statuses are added. `statuses` and `lifecycleGroups` are mutually exclusive; supplying both returns `400`. * `updatedAfter` — RFC 3339 timestamp; returns only domains last updated after this time. * `expiresBefore` — RFC 3339 timestamp; returns only domains expiring before this time. * `pageSize` — number of results per page, 1–200, defaults to 100. Pagination is cursor-based via `pageToken`; offset-based paging is not supported. ## Who is affected Any developer building portfolio management, renewal automation, or reporting tools on the Domains API. The `domains.domain:read` OAuth scope is required — the same scope used by `GET /v3/domains/domain-names/{domain-name}`. No existing endpoints are affected. ## Links * [Domains API reference](https://developer.godaddy.com/docs/references/rest/domains/v3/list-domains) — `GET /v3/domains/domain-names` request parameters and response schema * [DomainStatus values](https://developer.godaddy.com/docs/references/rest/domains/v3/list-domains?s-highlight=statuses\&path=statuses%00__0%7Cstatuses%5B%5D%00%23%2Fx-ext%2Fb594312#parameters.query.statuses) — full list of accepted `statuses` values * [Lifecycle groups](https://developer.godaddy.com/docs/references/rest/domains/v3/list-domains?s-highlight=lifecycleGroups\&path=lifecycleGroups%00__0%7ClifecycleGroups%5B%5D%00%23%2Fx-ext%2F847c074#parameters.query.lifecyclegroups) — accepted `lifecycleGroups` values # August 17, 2026: Domain availability and suggestion results now include `firstTermPrice` and `recommended` pricing fields (https://developer.godaddy.com/en/docs/api-users/changelog/domains-pricing-firsttermprice-recommended) --- title: >- August 17, 2026: Domain availability and suggestion results now include `firstTermPrice` and `recommended` pricing fields --- August 17, 2026 API Domains Changed We've added two optional fields to the `TermPrice` entries returned by `POST /v3/domains/check-availability`, `GET /v3/domains/check-availability`, and `GET /v3/domains/suggestions`, so you can surface promotional pricing and highlight the best-value term to customers without additional logic. `firstTermPrice` is the discounted price for the first term of a multi-year period. It's present when a first-term promotion applies to that period and typically omitted when `period` is 1 (where it equals `price`). `recommended` is a boolean flag that, when `true`, marks the best-value term based on active discounts or promotions. At most one entry in the `prices` array carries this flag; it is absent rather than `false` when no recommendation applies. Both fields are optional and additive. Existing integrations that do not read them are unaffected and require no changes. ## Links * [Domains API reference](https://developer.godaddy.com/docs/references/rest/domains/v3/get-domain-availability?s-highlight=firstTermPrice\&path=response%00%23%2Fcomponents%2Fschemas%2FAvailability%7Cprices%5B%5D%00%23%2Fx-ext%2F50f74db#response.200.applicationjson.response) — updated `TermPrice` schema # August 17, 2026: The Domains API now supports replacing individual DNS records via PUT /v3/domains/zones/{zone}/dns-records/{recordId} (https://developer.godaddy.com/en/docs/api-users/changelog/domains-replace-dns-record) --- title: >- August 17, 2026: The Domains API now supports replacing individual DNS records via PUT /v3/domains/zones/{zone}/dns-records/{recordId} --- August 17, 2026 API Domains New We've added `PUT /v3/domains/zones/{zone}/dns-records/{recordId}` to the Domains API, so you can fully replace a specific DNS record in a zone by its stable `recordId` without affecting other records. ## What changed A new endpoint is available: * `PUT /v3/domains/zones/{zone}/dns-records/{recordId}` — fully replaces an existing DNS resource record. All writable fields must be supplied in the request body: `name`, `type`, `data`, and `ttl`. Partial updates are not supported; omitting a writable field replaces it with its default. Changes are applied synchronously and the updated `DNSRecord` is returned in the response. The `DNSRecord` request body supports `A`, `AAAA`, `CAA`, `CNAME`, `MX`, `SRV`, and `TXT` record types. Type-specific fields — `priority` (MX, SRV), `weight`, `port`, `service`, `protocol` (SRV), `flag`, `tag` (CAA) — are required or optional depending on the record type. TTL must be between 600 and 86400 seconds. GoDaddy-managed `SOA` and `NS` records are read-only. Attempting to replace them returns `409 Conflict`. ## Who is affected Any developer managing DNS records programmatically via the Domains API. The `domains.dns:update` OAuth scope is required. No existing endpoints are affected. ## Links * [Domains API reference](https://developer.godaddy.com/docs/references/rest/domains/v3/replace-dns-record) — `PUT /v3/domains/zones/{zone}/dns-records/{recordId}` request and response schema # September 29, 2026: The Email API is now available for provisioning new mailboxes (https://developer.godaddy.com/en/docs/api-users/changelog/email-api-launch) --- title: >- September 29, 2026: The Email API is now available for provisioning new mailboxes featureflag: DOCS_EMAIL_API_ENABLED --- September 29, 2026 API Email New You can now provision and manage mailboxes on domains your account owns. The [Email API](https://developer.godaddy.com/docs/api-users/email) covers eligibility checks, mailbox creation, and mailbox lookup. ## What changed Four endpoints are available under `/v1/email`: * [`GET /v1/email/check-mailbox-eligibility`](https://developer.godaddy.com/docs/references/rest/email/check-mailbox-eligibility) — check whether an address can be provisioned and which entitlements are available. * [`POST /v1/email/mailboxes`](https://developer.godaddy.com/docs/references/rest/email/create-mailbox) — create a mailbox. * [`GET /v1/email/mailboxes`](https://developer.godaddy.com/docs/references/rest/email/list-mailboxes) — list mailboxes across account-owned domains, filtered by `status` and paged with `page` and `pageSize`. * [`GET /v1/email/mailboxes/{mailboxId}`](https://developer.godaddy.com/docs/references/rest/email/get-mailbox) — read one mailbox. Every endpoint authenticates with a Personal Access Token (PAT). The `email.mailbox:read` [scope](https://developer.godaddy.com/docs/api-users/email#oauth-scopes) grants the read operations; `email.mailbox:create` grants mailbox creation. Creation is asynchronous. `POST /v1/email/mailboxes` returns `202 Accepted` with the mailbox at `status: EXECUTING`; poll `GET /v1/email/mailboxes/{mailboxId}` until `status` reaches `COMPLETED` or `FAILED`. The create request requires an `Idempotency-Key` header, so retrying with the same key returns the original response instead of creating a second mailbox. We select `mailboxType` from the domain's entitlements — you don't set it. Some entitlements carry requirements — legal agreements you must accept before provisioning. The eligibility response lists them under `requirements`; pass matching `consents` in the create request body. The same flow is available from the terminal. The [`gddy` CLI](https://developer.godaddy.com/docs/api-users/cli/set-up) adds a `gddy email` command family: * `gddy email check-eligibility --email ` — check eligibility and list the accounts a mailbox can be created under. * `gddy email create --email ` — provision a mailbox. Pass one `--consent ` per outstanding requirement. `--account-id` is optional when exactly one eligible account is marked `default`. * `gddy email get ` — read one mailbox, and poll provisioning status. * `gddy email list` — list your mailboxes, with `--status`, `--field`, `--page`, `--page-size`, and `--total-required`. `gddy email create` needs the `email.mailbox:create` scope; the other three need `email.mailbox:read`. Run `gddy guide email` for a walkthrough of the eligibility-to-creation flow. ## Who is affected Available to developers with a GoDaddy account, through the REST endpoints or the `gddy` CLI. Both need a credential carrying the `email.mailbox` scopes, and mailboxes can only be provisioned on domains the authenticated account already owns. No existing integrations are affected; these are new endpoints and new commands, and no action is required. Every other `gddy` command family is unchanged. ## Links * [About the Email API](https://developer.godaddy.com/docs/api-users/email) — resources, mailbox statuses, eligibility, and scopes * [Provision a mailbox](https://developer.godaddy.com/docs/api-users/email/mailboxes/provision-mailboxes) — guide, from eligibility check to polling * [List and look up mailboxes](https://developer.godaddy.com/docs/api-users/email/mailboxes/manage-mailboxes) — guide, filtering and pagination * [Check eligibility reference](https://developer.godaddy.com/docs/references/rest/email/check-mailbox-eligibility), [Create mailbox reference](https://developer.godaddy.com/docs/references/rest/email/create-mailbox), [List mailboxes reference](https://developer.godaddy.com/docs/references/rest/email/list-mailboxes), [Get mailbox reference](https://developer.godaddy.com/docs/references/rest/email/get-mailbox) — endpoint schemas * [Set up the CLI](https://developer.godaddy.com/docs/api-users/cli/set-up) — install and authenticate `gddy` * [Generate a PAT](https://developer.godaddy.com/docs/api-users/auth/how-to) — create a token with the `email.mailbox` scopes * [Handle errors](https://developer.godaddy.com/docs/api-users/errors) — error envelope and idempotency behavior # September 29, 2026: The Hosting API is now available for deploying and operating Node.js apps (https://developer.godaddy.com/en/docs/api-users/changelog/hosting-api-launch) --- title: >- September 29, 2026: The Hosting API is now available for deploying and operating Node.js apps --- September 29, 2026 API Hosting New You can now deploy and operate Node.js apps on GoDaddy's hosting platform — from your own code, the `gddy` CLI, or an AI coding agent. The Hosting API covers the full app lifecycle, from source upload to a live custom domain. ## What changed The Hosting API is a REST API covering the app lifecycle. It's async-first: write operations return a job or deployment record that you poll to completion. Every app has a `preview` variant for iteration before you `publish` it to a live URL. Endpoints authenticate with a Personal Access Token holding the matching `hosting.*` scope: * **Apps** — `POST /apps` creates, plus read, update, and delete. * **Source** — upload a zip with `POST /apps/{appId}/imports`, or deploy from a GitHub repository connected in the web UI. * **Plans** — list your Web Hosting plans and attach one with `PUT /apps/{appId}/subscription` (required before publishing). * **Deployments** — `POST /apps/{appId}/deployments` publishes preview to production; `GET /apps/{appId}/deployments` lists history. * **Secrets** — `preview`/`publish` environment secrets via RFC 6902 JSON Patch; values are write-only. * **Logs, status, and domains** — read logs and runtime status, restart an app, and attach an optional custom domain. The same lifecycle is available from the terminal via the `gddy hosting` commands, and an AI coding agent can drive them through the [`gddy` agent skill](https://developer.godaddy.com/docs/api-users/cli/agent-skill). ## Who is affected Available to all developers with API access or the `gddy` CLI. The platform currently supports Node.js apps; other runtimes will be supported in future releases. Previewing an app needs no plan; publishing requires a Web Hosting plan attached to the app — buy one through the [Shopping API](https://developer.godaddy.com/docs/api-users/shopping/guides/purchase) if you don't have one. These are new endpoints and commands on a new surface. No existing Domains, Auctions, Commerce, or Web Hosting integration is affected, and no action is required. ## Links * [About the Hosting API](https://developer.godaddy.com/docs/api-users/hosting) — surface overview and what each guide covers * [Hosting core concepts](https://developer.godaddy.com/docs/api-users/hosting/concepts) — variants, async jobs, deployments, and scopes * [Deploy your Node.js app](https://developer.godaddy.com/docs/api-users/hosting/workflows/deploy-nodejs-app) — end-to-end deploy walkthrough * [Node.js app requirements](https://developer.godaddy.com/docs/api-users/hosting/app-requirements) — structure your app must have before uploading * [Hosting API reference](https://developer.godaddy.com/docs/references/rest/hosting) — endpoint schemas * [CLI hosting commands](https://developer.godaddy.com/docs/api-users/cli/reference#hosting) — the `gddy hosting` command table * [Agent skill for `gddy`](https://developer.godaddy.com/docs/api-users/cli/agent-skill) — let an AI coding agent run the CLI for you * [Buy a Web Hosting plan](https://developer.godaddy.com/docs/api-users/shopping/guides/purchase) — purchase a plan through the Shopping API * [Troubleshoot Node.js Hosting](https://developer.godaddy.com/docs/api-users/troubleshoot/hosting) — common errors and fixes # Changelog (https://developer.godaddy.com/en/docs/api-users/changelog) --- title: Changelog description: >- What's new in the GoDaddy Developer Portal — new endpoints, behavior changes, and deprecations. keywords: >- release notes, API updates, new endpoints, behavior changes, deprecations, version history, Domains Commerce Auctions releases --- Track updates to the GoDaddy Developer Portal, newest first. # September 29, 2026: The Shopping API is now available for catalog search, checkout, and order lookup (https://developer.godaddy.com/en/docs/api-users/changelog/shopping-api-launch) --- title: >- September 29, 2026: The Shopping API is now available for catalog search, checkout, and order lookup --- September 29, 2026 API Shopping New You can now search, buy, and read orders for GoDaddy products programmatically. The [Shopping API](https://developer.godaddy.com/docs/api-users/shopping) follows the Universal Commerce Protocol (UCP), so you can let your apps and AI agents buy GoDaddy products on your GoDaddy account. The catalog includes Web Hosting (Economy, Deluxe, and Ultimate) and Professional Email (Pro Light, Pro Plus, Premium, and Ultra). We plan to add more products. ## What changed New endpoints under `/v1/shopping`: * [`POST /v1/shopping/catalog/search`](https://developer.godaddy.com/docs/references/rest/shopping/search-catalog) — search products. * [`POST /v1/shopping/catalog/lookup`](https://developer.godaddy.com/docs/references/rest/shopping/lookup-catalog) — look up products by identifier. * [`POST /v1/shopping/catalog/product`](https://developer.godaddy.com/docs/references/rest/shopping/get-product) — get the details of one product. * [`POST /v1/shopping/checkout-sessions`](https://developer.godaddy.com/docs/references/rest/shopping/create-checkout) — create a checkout session. * [`GET /v1/shopping/checkout-sessions/{id}`](https://developer.godaddy.com/docs/references/rest/shopping/get-checkout) — read a session. * [`PUT /v1/shopping/checkout-sessions/{id}`](https://developer.godaddy.com/docs/references/rest/shopping/update-checkout) — update a session. * [`POST /v1/shopping/checkout-sessions/{id}/complete`](https://developer.godaddy.com/docs/references/rest/shopping/complete-checkout) — place the order. * [`GET /v1/shopping/orders/{id}`](https://developer.godaddy.com/docs/references/rest/shopping/get-order) — read an order. All endpoints need a Personal Access Token (PAT) with the [scope](https://developer.godaddy.com/docs/api-users/shopping#authentication) for the resource: `shopping.catalog:read`, `shopping.checkout:execute`, or `shopping.order:read`. The [`gddy` CLI](https://developer.godaddy.com/docs/api-users/cli/set-up) now includes the `gddy shopping catalog`, `gddy shopping checkout`, and `gddy shopping order` commands by default, without a beta flag. Run `gddy guide shopping` for a step-by-step purchase flow. The [`gddy` agent skill](https://developer.godaddy.com/docs/api-users/cli/agent-skill) tells AI agents to show the final total and each required agreement, and to get the user's explicit approval before checkout. ## Who is affected Available to developers with a GoDaddy account and API access or the `gddy` CLI. Reseller (private label) accounts are not supported. No existing integrations are affected; these endpoints and commands are additive, and no action is required. ## Links * [About the Shopping API](https://developer.godaddy.com/docs/api-users/shopping) — overview, authentication, and errors * [Search the catalog](https://developer.godaddy.com/docs/api-users/shopping/guides/search-catalog) — guide * [Purchase a product](https://developer.godaddy.com/docs/api-users/shopping/guides/purchase) — guide, from checkout to order * [Search catalog reference](https://developer.godaddy.com/docs/references/rest/shopping/search-catalog) — catalog endpoints * [Checkout reference](https://developer.godaddy.com/docs/references/rest/shopping/create-checkout) — checkout-session endpoints * [Get order reference](https://developer.godaddy.com/docs/references/rest/shopping/get-order) — order endpoint * [CLI setup](https://developer.godaddy.com/docs/api-users/cli/set-up) — install and configure `gddy` * [Generate a PAT](https://developer.godaddy.com/docs/api-users/auth/how-to) — create a token with the scopes you need # Agent skill for gddy (https://developer.godaddy.com/en/docs/api-users/cli/agent-skill) --- title: Agent skill for gddy description: >- Install the gddy agent skill so Claude Code or another AI coding agent can drive the GoDaddy CLI for you. keywords: >- npx skills add godaddy/cli, claude plugin marketplace add, Claude Code Cursor Codex Windsurf opencode, gddy --dry-run, AI coding agent CLI, skills installer, gddy auth status check agentNotes: permissions: - Any account scopes: - >- Depends on invoked command — the skill drives the gddy CLI, which inherits REST endpoint scopes rateLimit: >- N/A (installation only) — see /docs/api-users/rate-limits for the CLI's underlying call limits. idempotent: true destructive: false failureRecovery: >- Installation is safe to repeat. Re-run the install command to update or reinstall. Removing the skill does not affect the gddy CLI itself or its stored credentials. related: guides: - title: Set up the CLI href: /docs/api-users/cli/set-up - title: CLI reference href: /docs/api-users/cli/reference - title: GoDaddy MCP server href: /docs/api-users/mcp - title: Authenticate href: /docs/api-users/auth concepts: - title: About the GoDaddy CLI href: /docs/api-users/cli --- ## Overview The `gddy` agent skill helps an AI coding agent install and use the [`gddy` CLI](https://developer.godaddy.com/docs/api-users/cli/set-up) on your behalf. Installing the skill is a one-time setup. After it's in place, you can ask your agent to find a domain, check pricing, register it, or update DNS records in plain language, and it runs the actual `gddy` commands using your own authenticated session. After you install the skill, you can ask your agent things like: * "Set up `gddy` for me." (installs the CLI; you're prompted to log in automatically the first time a command needs it) * "Find available domains for a coffee subscription startup." * "Is `example.com` available, and what would it cost to register?" * "Add a CNAME record for `www` on `example.com` pointing to `example.github.io`." * "List the DNS records on `example.com`." Your agent will run the equivalent `gddy` commands, parse the JSON output, and summarize the result. It also knows how to use the CLI's self-documentation to stay current as `gddy` evolves (`gddy --help`, `gddy search `, `gddy tree`, and `gddy guide`). ## Safety notes The skill can purchase domains and modify DNS records if you ask it to. These guardrails apply when it does: * Domain purchase is real money and not reversible. The skill walks through the quote-then-purchase flow and confirms with you before finalizing a purchase. * `gddy dns set` and `gddy dns delete` are destructive — they replace or remove every matching record. The skill runs these with `--dry-run` first and shows you the change before applying it. * The skill acts with whatever credentials and environment your `gddy` CLI is currently authenticated against. Check with `gddy auth status` if you're unsure which account or environment your agent is operating on. This skill is not the same as the [GoDaddy MCP server](https://developer.godaddy.com/docs/api-users/mcp). The MCP server is a hosted, read-only service anyone can connect to for domain search and availability. The agent skill helps your coding agent install and run `gddy` itself, so it can do everything the CLI can do (including domain purchase and DNS management) using your own credentials. Go to [About the GoDaddy CLI](https://developer.godaddy.com/docs/api-users/cli#cli-agent-skill-mcp-server-and-rest-api) for a comparison of the CLI, the skill, and the MCP server. ## Install the skill The skill is compatible with [skills](https://github.com/vercel-labs/skills), a package-manager-style installer for agent skills. It supports Claude Code, Cursor, Codex, Windsurf, opencode, and many other compatible AI coding agents. The following procedure installs the `gddy` agent skill. **Claude Code** * In Claude Code, run the following commands: ```bash claude plugin marketplace add godaddy/cli claude plugin install gddy@godaddy ``` **Any other AI coding agent** * In your agent's terminal, run the following command: ```bash npx skills add godaddy/cli --skill gddy --agent $AGENT_NAME ``` Swap `$AGENT_NAME` for whichever agent you use (`claude-code`, `cursor`, `codex`, `windsurf`, `opencode`, ...). Run `npx skills add --help` for the full list of supported agents. # About the GoDaddy CLI (https://developer.godaddy.com/en/docs/api-users/cli) --- title: About the GoDaddy CLI description: >- What the GoDaddy CLI covers, how it authenticates, and how it relates to the agent skill and the MCP server. keywords: >- gddy command, gddy domain, gddy dns, CLI vs MCP server, CLI vs REST API, agent skill comparison, terminal domain management, install gddy, domain purchase CLI related: guides: - title: Quickstart href: /docs/api-users/quickstart - title: Authenticate href: /docs/api-users/auth - title: MCP server href: /docs/api-users/mcp --- ## Overview `gddy` is the GoDaddy CLI for domain and DNS operations. Install it once and use it from the terminal, or hand it off to an AI coding agent. ## Choose your guide ## CLI, agent skill, MCP server, and REST API | Tool | What it does | Account required? | Write access? | | --------------------------------------------------------- | -------------------------------------------------------------------------------------- | ----------------- | ------------- | | `gddy` CLI | Install locally. Search, purchase, and manage domains and DNS from the terminal. | Yes | Yes | | [Agent skill for `gddy`](https://developer.godaddy.com/docs/api-users/cli/agent-skill) | Runs `gddy` on your behalf inside an AI coding agent using your authenticated session. | Yes | Yes | | [GoDaddy MCP server](https://developer.godaddy.com/docs/api-users/mcp) | Hosted, read-only domain search and availability. No install. | No | No | | [REST API](https://developer.godaddy.com/docs/references/rest) | Direct API calls — full read/write access to domains, DNS, and more. | Yes | Yes | ## Related * [Set up the CLI](https://developer.godaddy.com/docs/api-users/cli/set-up) * [CLI reference](https://developer.godaddy.com/docs/api-users/cli/reference) * [Agent skill for `gddy`](https://developer.godaddy.com/docs/api-users/cli/agent-skill) * [GoDaddy MCP server](https://developer.godaddy.com/docs/api-users/mcp) * [Payment profile](https://developer.godaddy.com/docs/api-users/payment-profile) (required for domain purchase) * [Authenticate](https://developer.godaddy.com/docs/api-users/auth) # CLI workflow reference (https://developer.godaddy.com/en/docs/api-users/cli/reference) --- title: CLI workflow reference description: >- Reference for common gddy workflows: authentication, Domains, DNS, output flags, and payment methods. keywords: >- gddy auth login, gddy domain available, gddy domain quote, gddy domain purchase --quote-token, gddy dns set, gddy dns delete --dry-run, gddy tree, gddy guide, gddy hosting, gddy api, gddy pat add related: guides: - title: Set up the CLI href: /docs/api-users/cli/set-up - title: Agent skill for gddy href: /docs/api-users/cli/agent-skill - title: Authenticate href: /docs/api-users/auth concepts: - title: Rate limits href: /docs/api-users/rate-limits --- ## Overview ## Other command surfaces The installed CLI also includes the following command families. They are intentionally not expanded into a second, incomplete catalog on this page; use the listed help command to inspect the version installed on your machine. | Command family | Use it for | Discover commands | | ------------------ | ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | | `gddy api` | Browse API domains and operations, inspect schemas and parameters, call REST or GraphQL operations | `gddy api --help` | | `gddy hosting` | Create and manage hosting apps, source uploads, deployments, GitHub connections, secrets, logs, and status | `gddy hosting --help` | | CLI administration | Environments (`env`), Personal Access Tokens (`pat`), updates (`update`), feature flags (`flags`), and shell completion | `gddy --help` | | CLI discovery | Search commands and built-in guides, print the tree, or generate completions | `gddy search `, `gddy guide`, `gddy tree`, `gddy completion --help` | ## Authentication and credentials The following table lists the `gddy` commands for authentication and credential management: | Command | Description | | --------------------------------- | ------------------------------------------------------------------------------ | | `gddy auth login` | Authenticate using browser-based login | | `gddy auth status` | Show the current authentication state | | `gddy pat add --env ` | Store a Personal Access Token for non-interactive authentication (CI, scripts) | | `gddy env get` | Show the active environment | | `gddy env set ` | Set the active environment (for example, `ote` or `prod`) | ## Domains The `gddy domain` namespace covers domain availability, search, registration, and management. ### Domain search and purchase The following table lists the `gddy` commands for domain search and purchase: | Command | Description | Note | | -------------------------------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------ | | `gddy domain available ` | Check whether a single domain is available to register | | | `gddy domain available --check-type full` | Full registry check | Provides a slower, definitive result | | `gddy domain suggest "" --tlds com,net,io --limit 5` | Get domain name suggestions for a keyword or phrase | | | `gddy domain quote ` | Quote a domain | | | `gddy domain agreements --tld ` | Retrieve the ICANN agreements required for a registration | | | `gddy domain purchase --quote-token --agree --confirm` | Register the domain from a `gddy domain quote` token | Charges the account (use `--confirm` to proceed) | | `gddy domain contacts init` | Write a `contacts.toml` template for reuse across purchases | | `gddy domain purchase` doesn't take a domain name directly. It registers whatever `gddy domain quote ` locked in, using that command's `--quote-token` (valid for about 10 minutes). Run `gddy guide domain-purchase` for the full walkthrough. ### Domain management The following table lists the `gddy` commands for domain management: | Command | Description | | ---------------------------------- | --------------------------------------------- | | `gddy domain list` | List all domains on the authenticated account | | `gddy domain list --status ACTIVE` | Filter domains by status | | `gddy domain get ` | Get full detail for a single domain | ## DNS The following table lists the `gddy` commands for DNS management: | Command | Description | | ----------------------------------------------------------------------- | --------------------------------------- | | `gddy dns list ` | List all DNS records on a domain | | `gddy dns list --type A --name www` | Filter by record type and name | | `gddy dns add --type A --name www --data 192.0.2.10 --ttl 600` | Add a DNS record | | `gddy dns set --type A --name www --data 192.0.2.20 --ttl 600` | Replace all records for a type and name | | `gddy dns delete --type A --name www` | Delete all records for a type and name | `gddy dns add` appends records. `gddy dns set` replaces every record for the type and name combination. `gddy dns delete` removes every record for the type and name (it doesn't remove GoDaddy-managed `NS` or `SOA` records). Use `--dry-run` with destructive commands to preview changes. ## Hosting The following table lists the key `gddy` commands for managing hosting applications: | Command | Description | | ---------------------------------------------------------------------------------------- | --------------------------------- | | `gddy hosting app create --app-type --name ` | Provision a new app | | `gddy hosting operation get --operation-id ` | Poll until provisioning complete | | `gddy hosting source upload --app-id --file ` | Upload code | | `gddy hosting source status --app-id --import-id ` | Poll until code upload complete | | `gddy hosting app get --app-id ` | Get app preview URL | | `gddy hosting subscription list --hosting-product ` | List customer's plans by product | | `gddy hosting subscription attach --app-id --subscription-id ` | Attach app to a hosting plan | | `gddy hosting deployment publish --app-id ` | Publish the app | | `gddy hosting deployment get --app-id --deployment-id ` | Poll deployment completion status | | `gddy hosting app get --app-id ` | Get app published URL | ## Output and flags Every command returns structured output. In an interactive terminal the default is human-readable; in pipes, CI, and scripts the default is JSON. ```json { "data": { "apiUrl": "https://api.ote-godaddy.com", "env": "ote" } } ``` **Format:** `-o, --output ` (shortcuts: `--json`, `--human`, `--toon`) The following table lists the available output shaping and execution flags: | Flag | What it does | | ------------------------------------------ | ------------------------------------------------------------- | | `--fields ` | Select output fields | | `--filter ` | Filter list items | | `--expr ` | Transform the whole result | | `--limit` / `--offset` | Paginate client-side | | `--verbose [fields]` | Add execution metadata | | `--schema` | Print a command's documented output fields without running it | | `--env ` | One-off environment override | | `--dry-run` | Preview a supported mutation | | `--credential-store ` | Choose where credentials are stored | | `--debug ` | Diagnostic logging | | `--timeout ` | For example `60s` or `5m` | ## Payment methods The following table lists the `gddy` commands for payment methods: | Command | Description | | -------------------------- | --------------------------------------------------------- | | `gddy payment-methods add` | Open the payment-methods page for the current environment | Domain forwarding, registry lock, renewals, and contact updates aren't in the CLI yet. Use the REST API for those operations. Go to [About the GoDaddy CLI](https://developer.godaddy.com/docs/api-users/cli) for what `gddy` covers. # Set up the CLI (https://developer.godaddy.com/en/docs/api-users/cli/set-up) --- title: Set up the CLI description: >- Install the GoDaddy CLI as `gddy` and make a first call—`gddy` handles authentication automatically when a command needs it. keywords: >- install.sh install.ps1, ~/.local/bin gddy, %LOCALAPPDATA% Programs gddy, GDDY_PAT environment variable, gddy auth login, gddy pat add CI non-interactive, gddy domain suggest, gddy domain purchase --agree agentNotes: permissions: - Any account scopes: - >- Depends on invoked command — CLI wraps REST endpoints and inherits their scopes rateLimit: >- Rate-limited per credential per window (per underlying REST call). Go to /docs/api-users/rate-limits for current values. idempotent: true destructive: false failureRecovery: >- CLI is a wrapper — same recovery semantics as the underlying REST endpoint. Config is stored in ~/.config/gddy/ (Linux/macOS) or the platform equivalent. Delete config to reset credentials. related: guides: - title: Quickstart href: /docs/api-users/quickstart - title: Authenticate href: /docs/api-users/auth - title: CLI reference href: /docs/api-users/cli/reference - title: Agent skill for gddy href: /docs/api-users/cli/agent-skill - title: GoDaddy MCP server href: /docs/api-users/mcp concepts: - title: About the GoDaddy CLI href: /docs/api-users/cli - title: Rate limits href: /docs/api-users/rate-limits --- ## Overview The CLI installer installs the GoDaddy CLI as `gddy`. If you prefer raw HTTP calls instead, go to the [API quickstart](https://developer.godaddy.com/docs/api-users/quickstart). You can also have an AI coding agent install and drive `gddy` for you by using the [agent skill](https://developer.godaddy.com/docs/api-users/cli/agent-skill). For read-only domain search without installing anything, go to the [MCP server](https://developer.godaddy.com/docs/api-users/mcp). Go to [About the GoDaddy CLI](https://developer.godaddy.com/docs/api-users/cli) for what `gddy` covers and how it relates to the agent skill and the MCP server. The install scripts come from the public `godaddy/cli` repository. You don't need GitHub authentication to install or update the CLI. ## Install or update the CLI Run the installer for your shell. Re-running the same command updates `gddy` to the latest release. The following procedure installs or updates the CLI. **macOS / Linux** The script downloads the `gddy` binary, verifies its checksum, and installs it to `~/.local/bin`. It doesn't modify your `PATH`. 1. Run the following command: ```bash curl -fsSL https://github.com/godaddy/cli/releases/latest/download/install.sh | bash ``` 2. (*Optional*) If `~/.local/bin` is not already in your path, add it yourself: ```bash export PATH="$HOME/.local/bin:$PATH" ``` Add the same line to your shell profile (`~/.zshrc` or `~/.bashrc`) to persist it across new terminals. This also works from Git Bash, MSYS2, or Cygwin on Windows. **Windows PowerShell** The script downloads the `gddy.exe` binary, verifies its checksum, installs it to `%LOCALAPPDATA%\Programs\gddy`, and adds that directory to your user `PATH` (open a new terminal to pick it up). * Run the following command: ```powershell irm https://github.com/godaddy/cli/releases/latest/download/install.ps1 | iex ``` If PowerShell blocks the command with an execution-policy error (common on corporate-managed machines that default to `Restricted`), run `Set-ExecutionPolicy -Scope Process Bypass` first and try again, or download `install.ps1` and inspect it before running it directly. ## Verify the install Verify the install by checking the version and help message. If your shell can't find `gddy`, the install directory isn't on your `PATH`. The following procedure verifies the installation was successful. 1. Open a new terminal if the installer changed your `PATH`, then run: ```bash gddy --version gddy --help ``` 2. (*Optional*) Confirm the binary exists (if your shell can't find `gddy`): **macOS / Linux** `~/.local/bin/gddy` **Windows PowerShell** `%LOCALAPPDATA%\Programs\gddy\gddy.exe` ## Authenticate You don't need to log in ahead of time. Any command that needs authentication opens a browser for OAuth login automatically the first time you run it. The following procedure logs in early, which is useful if you want to confirm your session before running commands or switch accounts. 1. Run the following command: ```bash gddy auth login ``` 2. Confirm the CLI has an active session: ```bash gddy auth status ``` CI pipelines, SSH sessions, and other non-interactive environments can't complete the browser flow, so authentication has to happen ahead of time there. Generate a [Personal Access Token](https://developer.godaddy.com/docs/api-users/auth/how-to) and store it for `gddy` to use instead: ```bash echo 'gd_pat_...' | gddy pat add --env prod "CI token" ``` Or skip local storage and supply it per-run with the `GDDY_PAT` (or `GDDY_PAT_`) environment variable. The CLI checks for a PAT before falling back to OAuth. Run `gddy guide auth` for the full walkthrough. ## Add a payment method Domain purchase requires a billing method on your GoDaddy account. If you haven't logged in yet, `gddy` prompts you to before opening the payment-methods page. The following procedure adds a payment method. * Open the payment-methods page for your environment: ```bash gddy payment-methods add ``` Go to [Set up a payment profile](https://developer.godaddy.com/docs/api-users/payment-profile) for information on account URLs, verification steps, and common billing errors. ## Make a first call The following procedure makes a first call to the Domains API to get available domain suggestions for "coffee shop". If you haven't logged in yet, `gddy` prompts you to the first time one of these commands needs it. 1. Ask the Domains API for available domain suggestions for "coffee shop": ```bash gddy domain suggest "coffee shop" --tlds com --limit 5 ``` 2. Check a suggestion directly: ```bash gddy domain available ``` 3. After you've found an available domain, get a price quote before purchasing: ```bash gddy domain quote ``` 4. Complete the purchase using the quote token from the previous step: ```bash gddy domain purchase --quote-token --agree --confirm ``` `gddy domain purchase` registers the domain and charges the payment method you added earlier. The quote token from step 3 is only valid for about 10 minutes, and `--confirm` is required to finalize the charge. Run `gddy guide domain-purchase` for the full walkthrough, including how to supply registrant contact details. Go to [CLI workflow reference](https://developer.godaddy.com/docs/api-users/cli/reference) for command details on domain management, DNS, Platform Apps, hosting, and payment methods. Run `gddy tree` for the exact complete command list in your installed version. # 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.' keywords: >- storeId, channelId, SKU, SKUGroup, lineItem, customerId, DRAFT OPEN CLOSED, order status values, subgraph endpoint, entity model 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. # About the Commerce API (https://developer.godaddy.com/en/docs/api-users/commerce) --- title: About the Commerce API description: >- Build integrations to manage stores, catalogs, orders, customers, and fulfillment with GoDaddy Commerce. keywords: >- storeId, GraphQL subgraph, REST endpoints, ecommerce API, merchant store integration, shop management, product inventory, order management API related: concepts: - title: Commerce core concepts href: /docs/api-users/commerce/concepts guides: - title: Authenticate href: /docs/api-users/auth - title: Manage a store href: /docs/api-users/commerce/set-up-a-store --- ## 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](https://www.godaddy.com/payments) for an overview of what's included and [Get started with GoDaddy Payments](https://www.godaddy.com/help/get-started-with-godaddy-payments-40721) to create your account and activate your store. | | Personal Access Token (PAT) | A token you use to authenticate your API calls. | Go to [Authenticate](https://developer.godaddy.com/docs/api-users/auth) 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](https://developer.godaddy.com/docs/api-users/commerce#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](https://www.godaddy.com/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 `storeId`s, 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](https://developer.godaddy.com/docs/api-users/commerce/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](#your-stores) | | Channel | List sales channels | REST | [List sales channels](https://developer.godaddy.com/docs/api-users/commerce/set-up-a-store/channel) | | Catalog | Create and manage SKUs | GraphQL | [Manage catalog items](https://developer.godaddy.com/docs/api-users/commerce/manage-catalog) | | Order | Create and track orders | GraphQL | [Process an order](https://developer.godaddy.com/docs/api-users/commerce/manage-orders-and-customers) | | Customer | Create and manage customers | REST | [Manage a customer](https://developer.godaddy.com/docs/api-users/commerce/manage-orders-and-customers/customer) | | Transaction | View payment transactions | REST | [View transactions](https://developer.godaddy.com/docs/api-users/commerce/manage-orders-and-customers/transaction) | | Tax | Configure tax rates | GraphQL | [Configure taxes](https://developer.godaddy.com/docs/api-users/commerce/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](https://developer.godaddy.com/docs/api-users/auth)). * **Errors** — One machine-readable envelope; match on the stable `code`, not the message ([Handle errors](https://developer.godaddy.com/docs/api-users/errors)). * **Rate limits** — Per-credential limits; read the headers rather than hardcoding numbers ([Handle rate limits](https://developer.godaddy.com/docs/api-users/rate-limits)). * **Pagination** — Consistent list models; follow the shared pagination pattern ([Paginate results](https://developer.godaddy.com/docs/api-users/pagination)). * **Idempotency** — Per-namespace retry rules; check each how-to's Agent Notes before you retry ([Building reliable integrations](https://developer.godaddy.com/docs/api-users/concepts/building-reliable-integrations)). # Building reliable integrations (https://developer.godaddy.com/en/docs/api-users/concepts/building-reliable-integrations) --- title: Building reliable integrations description: >- Error handling, rate limiting, idempotency, and retry patterns for the GoDaddy Domains API — the operational considerations that separate working code from production-ready code. keywords: >- exponential backoff, Idempotency-Key, jitter, circuit breaker, at-least-once delivery, 503, webhook retry related: guides: - title: Handle errors href: /docs/api-users/errors - title: Rate limits href: /docs/api-users/rate-limits - title: Troubleshoot authentication href: /docs/api-users/troubleshoot/authentication concepts: - title: How GoDaddy APIs work href: /docs/api-users/concepts/how-godaddy-apis-work - title: Domains core concepts href: /docs/api-users/domains/concepts --- ## Overview This page covers the operational patterns for building an integration that holds up in production — how to handle errors correctly, manage rate limits, avoid duplicate charges through idempotency, and implement retry logic that doesn't make failures worse. The patterns here apply to the GoDaddy Domains API specifically but reflect general principles for working with any REST API. ## Error handling The GoDaddy API returns a consistent JSON error envelope on every failure: ```json { "code": "DOMAIN_NOT_AVAILABLE", "message": "The domain you requested is not available.", "fields": [ { "code": "REQUIRED", "message": "is required", "path": "contactRegistrant.email", "pathRelated": "" } ] } ``` The `code` field is the key identifier. HTTP status codes alone are not sufficient — two `422` responses can require completely different handling depending on their `code`. Always read `code` before branching on a failure. ### Status code guide The following table describes the different status codes. | Status | What it means in practice | | -------------------------- | ---------------------------------------------------------------------------------------------- | | `200`, `201`, `202`, `204` | Success. `202 Accepted` means the operation is async — poll for completion. | | `400` | Your request is malformed. Check `fields[]` for which field failed validation. | | `401` | Token is missing, expired, or revoked. Regenerate and retry. | | `403` | Token is valid but lacks the required scope, or the account isn't eligible. | | `404` | The resource doesn't exist, or the account can't see it. Don't retry without verifying state. | | `409` | Conflict — something about the current state prevents the operation. | | `422` | Request structure is valid but violates a business rule. Check `code` to determine the reason. | | `429` | Rate limit exceeded. Wait for `Retry-After` seconds. | | `5xx` | Server error. Safe to retry with exponential backoff. | ### What to retry and what not to The key distinction is safe vs. unsafe operations: | Retry safety | Operations | Explanation | | -------------------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | Safe to retry unconditionally | `GET` | Read-only. No side effects (a timeout can always be retried). | | Safe to retry with idempotency | `PUT`, `PATCH` on domain settings (lock state, auto-renew, nameservers) | Idempotent (replaying with the same body produces the same result). | | Unsafe to retry without checking state first | `POST` for registration, renewal, or transfer | These charge the account. A network timeout doesn't mean the operation failed. Always `GET` the resource before retrying. | ## Idempotency Idempotency means that making the same request multiple times produces the same result as making it once. For read operations and most updates, this is automatic. For registrations, it requires explicit action. ### The `Idempotency-Key` header The registration endpoint (`POST /v3/domains/registrations`) requires an `Idempotency-Key` header. Generate a UUID per request and include it on every registration call: ```bash curl -X POST "https://api.godaddy.com/v3/domains/registrations" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ ... }' ``` If you send the same `Idempotency-Key` on a retry, the server returns the original response without creating a second order. This is the safe way to retry a registration after a network timeout. ### Checking state before retrying (transfer and renewal) Transfer and renewal endpoints do not support `Idempotency-Key`. For those operations, check state before retrying any money-moving operation: 1. A request times out or returns a `5xx`. 2. Before retrying: call `GET /v1/domains/{domain}` (or the relevant read endpoint). 3. If the operation succeeded (domain is present, `renewAuto` changed, status is `PENDING_TRANSFER`), do not retry. 4. If the operation didn't happen, retry the original request. This pattern avoids double-charges on endpoints where idempotency keys aren't available. ## Rate limiting The API enforces per-credential rate limits (see [Rate limits](https://developer.godaddy.com/docs/api-users/rate-limits) for current values). When the limit is exceeded, the API returns: ``` HTTP/1.1 429 Too Many Requests Retry-After: 30 RateLimit-Limit: 600 RateLimit-Remaining: 0 RateLimit-Reset: 1399 ``` ### Handling 429 in code The only correct response to a `429` is to wait. The `Retry-After` header gives the exact number of seconds. ```js async function callWithRetry(url, options, maxRetries = 3) { for (let attempt = 0; attempt < maxRetries; attempt++) { const res = await fetch(url, options); if (res.status === 429) { const retryAfter = parseInt(res.headers.get("Retry-After") ?? "10", 10); await new Promise((r) => setTimeout(r, retryAfter * 1000)); continue; } return res; } throw new Error("Max retries exceeded"); } ``` ### Staying within limits The rate limit is generous for interactive use cases but can be consumed quickly by bulk operations. For batch jobs: * Spread requests over time — don't send a burst of requests in the first second and then wait for the window to reset. * Use the list endpoints with maximum `limit` values to reduce the number of calls needed. * Cache read results where the underlying data changes slowly (for example, domain lock state rarely changes so there's no need to poll it every minute). ## Async operations Some operations complete asynchronously. The API returns `202 Accepted` immediately with an operation object, and you poll until the operation reaches a terminal state. Nameserver replacement is the primary async operation in the Domains v3 API. The response includes a `Location` header pointing to the operation URL. Poll that URL until `status` is `COMPLETE` or `FAILED`. For domain registration, the operation completes synchronously in most cases, but the domain may briefly appear in `EXECUTING` status — particularly for first-time purchases on new accounts. Poll `GET /v1/domains/{domain}` until `status` is `ACTIVE`. ## Exponential backoff For retryable errors (`5xx`, `429` after the wait period), use exponential backoff with jitter rather than fixed-interval retries. Fixed-interval retries from many clients simultaneously create retry storms that make server problems worse. A simple backoff pattern: ```python import time, random def retry_with_backoff(fn, max_attempts=4, base_delay=1.0): for attempt in range(max_attempts): try: return fn() except RetryableError as e: if attempt == max_attempts - 1: raise delay = base_delay * (2 ** attempt) + random.uniform(0, 1) time.sleep(delay) ``` The delays would be approximately: 1s, 2s, 4s — with up to 1 second of random jitter added to each. This spreads retry load across time and avoids synchronized retry waves. ## Secrets management PATs are long-lived credentials that grant real access to real accounts. Treat them like passwords: * Never hardcode tokens in source code or commit them to version control. * Store tokens in environment variables or a secrets manager (AWS Secrets Manager, HashiCorp Vault, etc.). * Use separate tokens for separate environments — a production token should never appear in a development codebase. * Rotate tokens on a regular schedule and immediately on suspected compromise. * Scope tokens to the minimum permissions required for the integration. Go to [How to Authenticate](https://developer.godaddy.com/docs/api-users/auth/how-to) for token generation steps, or [Authenticate](https://developer.godaddy.com/docs/api-users/auth) for the scope reference. # How GoDaddy APIs work (https://developer.godaddy.com/en/docs/api-users/concepts/how-godaddy-apis-work) --- title: How GoDaddy APIs work description: >- The architecture, authentication model, environments, and request conventions shared across all GoDaddy REST APIs. keywords: >- OTE, api.godaddy.com, api.ote-godaddy.com, sandbox, v1 v2 v3, sso-key vs PAT, JSON REST, Bearer token, scopes related: guides: - title: Authenticate href: /docs/api-users/auth - title: Make your first call href: /docs/api-users/quickstart - title: Handle errors href: /docs/api-users/errors - title: Rate limits href: /docs/api-users/rate-limits concepts: - title: Domains core concepts href: /docs/api-users/domains/concepts - title: Building reliable integrations href: /docs/api-users/concepts/building-reliable-integrations --- ## Overview This page explains the architecture and design principles shared across GoDaddy REST APIs — how authentication works, how environments are separated, and what to expect from API behavior. Read this before you build to ensure you have a full understanding of how GoDaddy APIs are structured. ## API architecture GoDaddy APIs are REST APIs that accept JSON request bodies and return JSON responses. All requests go to a single base URL (`api.godaddy.com` for production), and all API calls require an `Authorization` header carrying a Bearer token. Every API call follows the same pattern: 1. Include `Authorization: Bearer ` in the request header. 2. The gateway validates the token and checks its scopes. 3. A valid request is routed to the correct API version and resource handler. 4. The handler returns a JSON response with a standard HTTP status code. There is no API key rotation scheme, no HMAC signing, and no session management. Every request is independently authenticated with the Bearer token. ## Authentication model GoDaddy uses Personal Access Tokens (PATs) for API authentication. A PAT is a long-lived credential tied to a GoDaddy account with a configurable set of capability scopes. ### Why scopes matter Scopes determine what a token can do, not just who it belongs to. Scopes are additive: a single token can carry multiple scopes, and a token is limited to exactly what its scopes allow — even if the underlying account has broader access. The scope model exists so that integrations can be given the minimum permissions they need. A read-only analytics pipeline doesn't need write scopes. A DNS automation tool doesn't need purchase scopes. Scopes follow the pattern `api.resource:operation`. For example, `domains.domain:read` grants read access to domain resources, and `commerce.order:complete` grants the ability to finalize an order. Go to [Domains API concepts](https://developer.godaddy.com/docs/api-users/domains/concepts) or [Commerce core concepts](https://developer.godaddy.com/docs/api-users/commerce/concepts) for the scope tables for each API. Go to [Authenticate](https://developer.godaddy.com/docs/api-users/auth) for the full scope reference, or [How to Authenticate](https://developer.godaddy.com/docs/api-users/auth/how-to) for token creation steps. ### Legacy credentials The older `sso-key` credential format (`sso-key :`) is still supported for v1 API endpoints but is scheduled for deprecation in 2026. New integrations should use PATs exclusively. PATs are required for all v3 endpoints. ## Environments GoDaddy provides a single production environment for API development. Some API calls require a funded payment method, can incur costs, and create real domain records. Scope your calls carefully. Actions taken in production are real, billable, and often irreversible. ## Request and response format All API requests and responses use JSON. A few conventions apply across the entire API surface: **Content-Type**: Always send `Content-Type: application/json` on requests with a body. **Accept**: Send `Accept: application/json` on read requests. The API defaults to JSON but specifying it is good practice. **Monetary values**: Monetary units vary by API. Check the API reference for the unit a specific API uses. * Domains, Auctions, and legacy REST APIs use micro-units. Divide by 1,000,000 to get the currency value. A `price` of `11990000` in `USD` is `$11.99`. * The Shopping API uses ISO 4217 minor units. For USD, divide by 100. An `amount` of `999` in `USD` is `$9.99`. **Timestamps**: All timestamps are ISO 8601 in UTC (for example, `2026-03-15T00:00:00.000Z`). **Pagination**: v1 list endpoints use `limit` and `marker` for cursor-based pagination. v3 list endpoints use `page` and `pageSize`. Go to [Pagination](https://developer.godaddy.com/docs/api-users/pagination) for examples. ## Rate limits The API enforces per-credential rate limits. Exceeding the limit returns `429 Too Many Requests` with a `Retry-After` header indicating how many seconds to wait. Rate limits apply per credential. If you have multiple integrations using the same PAT, their request rates are pooled. Use separate PATs for independent workloads if you expect them to approach the limit independently. Go to [Rate limits](https://developer.godaddy.com/docs/api-users/rate-limits) for current limits and handling guidance. ## Error structure All errors return a consistent JSON envelope regardless of the HTTP status code: ```json { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource could not be found.", "fields": [] } ``` The `code` field is the machine-readable identifier to branch on. The HTTP status code alone is not sufficient — two `422` responses with different `code` values require different handling. Go to [Handle errors](https://developer.godaddy.com/docs/api-users/errors) for the full error reference, status code guide, and retry semantics. # Domains core concepts (https://developer.godaddy.com/en/docs/api-users/domains/concepts) --- title: Domains core concepts description: >- The concepts behind domain registration, DNS, WHOIS, and the domain lifecycle — what the terms mean and why they matter when building with the GoDaddy Domains API. keywords: >- TLD, nameserver, A record, CNAME, MX record, registrar, EPP, transfer lock, ICANN, Redemption period, privacy protection related: guides: - title: Search domain availability href: /docs/api-users/domains/search - title: Register a domain href: /docs/api-users/domains/register - title: Manage DNS records href: /docs/api-users/domains/manage/dns - title: Manage renewals href: /docs/api-users/domains/manage/renewals - title: Update contacts href: /docs/api-users/domains/manage/update-contacts concepts: - title: How GoDaddy APIs work href: /docs/api-users/concepts/how-godaddy-apis-work - title: Building reliable integrations href: /docs/api-users/concepts/building-reliable-integrations --- ## Overview This page explains the concepts behind domain registration and management — what registrars, registries, DNS, and the domain lifecycle mean at a technical level. Understanding these concepts makes the API's behavior more predictable and helps you build integrations that handle edge cases correctly. ## Domain registration A domain name is a human-readable address registered in a global distributed database. When you register a domain, you're leasing the right to use that name for a fixed period (typically 1–10 years) from the registry \[the organization that manages a top-level domain (TLD)]. ### Registrars and registries Two distinct organizations are involved in every domain registration: | Organization | Role | Example | | ------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | | **Registry** | Manages a TLD. Maintains the authoritative database of all registered domains under that TLD. Sets policy. | Verisign (`.com`, `.net`), Public Interest Registry (`.org`) | | **Registrar** | An accredited middleman. Takes registration requests from customers and submits them to the registry. | GoDaddy, Namecheap, Cloudflare Registrar | GoDaddy is an ICANN-accredited registrar. When you register a domain through the GoDaddy API, GoDaddy submits the registration to the appropriate registry on your behalf. The registry is the source of truth. A domain doesn't exist until the registry acknowledges it. ### What you own When you register a domain, you don't own it in the traditional sense. You hold the right to use it for the registration period. The registry can reclaim domains that violate its policies (for example, trademark disputes decided by ICANN's UDRP process). Registration creates a record in the registry's WHOIS database associating the domain with a registrant contact. The registrant contact is the legal owner for the duration of the registration. ## The domain lifecycle Domains pass through defined states from registration to expiration and beyond. | Status | Meaning | | -------------------- | -------------------------------------------------------------------------------------------------------------- | | `ACTIVE` | Registration is current. Domain resolves normally. | | `EXPIRED` | Expiration date has passed but the domain is in the grace period. Renewal at standard price is still possible. | | `PENDING_TRANSFER` | An inbound transfer is in progress. Registry is processing the move from another registrar. | | `CANCELLED_TRANSFER` | A transfer was rejected or cancelled. The domain remains at the current registrar. | ### Grace periods After expiration, GoDaddy provides a recovery window before the domain is permanently released. The exact timing varies by TLD, but the general pattern for gTLDs is: * **0–12 days after expiration**: Standard renewal pricing applies. The domain is still in your account. * **12–42 days after expiration**: Redemption period. The domain can be recovered but with additional fees. It's no longer visible in your account. * **After redemption period**: The domain is released back to the registry and becomes available for registration by anyone. ccTLDs (country-code TLDs like `.uk`, `.de`, `.ca`) have significantly different timelines — some expire immediately with no grace period. Always verify the TLD's expiration policy before building automated renewal logic. ## DNS and nameservers DNS (Domain Name System) translates domain names into IP addresses (and other resource records). It's a distributed hierarchical system — no single server knows everything. ### Authoritative nameservers Every domain has authoritative nameservers (the servers that hold the definitive DNS records for that domain). When a resolver looks up `example.com`, it eventually reaches `example.com`'s authoritative nameservers and gets the answer directly from them. At registration, GoDaddy assigns its own authoritative nameservers to your domain by default. While GoDaddy's nameservers are authoritative, you manage DNS records through the GoDaddy API (`/v3/domains/zones/{zone}/dns-records`). If you want to use a different DNS provider (like Cloudflare or Route 53.), you delegate authority by replacing the nameservers with that provider's servers (`PUT /v3/domains/domain-names/{domain-name}/nameservers`). After delegation, GoDaddy's API can no longer manage DNS records for the domain and the other provider's tools apply. ### DNS record types The following table lists the different DNS record types. | Type | Purpose | Example value | | ------- | ------------------------------------------------------------------- | --------------------------------------- | | `A` | Maps a hostname to an IPv4 address | `192.0.2.1` | | `AAAA` | Maps a hostname to an IPv6 address | `2001:db8::1` | | `CNAME` | Alias (maps a hostname to another hostname) | `www → example.com` | | `MX` | Mail exchange (routes email for the domain) | `mail.example.com` (priority 10) | | `TXT` | Arbitrary text (used for verification, SPF, DKIM) | `"v=spf1 include:_spf.google.com ~all"` | | `NS` | Nameserver delegation (authoritative servers for a zone) | `ns1.domaincontrol.com` | | `CAA` | Certificate Authority Authorization (which CAs may issue SSL certs) | `0 issue "letsencrypt.org"` | | `SRV` | Service record (protocol-specific host and port) | `_http._tcp 0 5 80 www.example.com` | ### DNS propagation When you change a DNS record, the new value doesn't appear instantly everywhere. DNS changes propagate through a cache hierarchy. Each record has a TTL (time-to-live) value that controls how long resolvers cache it before checking for updates. With GoDaddy's authoritative DNS: * Changes applied through the v3 API take effect synchronously on GoDaddy's nameservers. * Cached copies elsewhere on the internet expire at the rate set by the record's TTL (minimum 600 seconds, maximum 86400 seconds on GoDaddy's v3 API). * Resolvers that haven't cached the old value will see the new one immediately. Propagation delay means there's a window after a DNS change where different users see different values depending on which resolver they use. For this reason, DNS changes for critical infrastructure (mail routing, SSL validation) should be planned and staged and not made under pressure. ## WHOIS and contact privacy WHOIS is a protocol for querying the registry's public contact database. It exposes the registrant name, email, phone, and mailing address for every registered domain unless privacy protection is enabled. ### Contact roles Every domain registration requires a registrant contact. Some registrations can require up to four contact roles. The following table lists the contact roles and their purposes: | Role | Purpose | | -------------- | ----------------------------------------------------------------------------- | | **Registrant** | Legal owner of the domain. Required. | | **Admin** | Administrative contact. Defaults to registrant if omitted. | | **Billing** | Billing contact for renewal charges. Defaults to registrant if omitted. | | **Tech** | Technical contact for DNS-related matters. Defaults to registrant if omitted. | ICANN requires registrant contact information to be accurate. Providing false information can result in domain suspension. Use WHOIS privacy if you want to mask your contact details from the public database. Privacy services replace the real contact information with the privacy service's placeholder data in the WHOIS record. ## Domain locking Registry lock (the `clientTransferProhibited` status flag) is a security feature that prevents other registrars from initiating a transfer out of GoDaddy without your explicit action. While locked, the registry will reject transfer requests from competing registrars. Lock is enabled by default at registration. It has no effect on DNS resolution, email delivery, SSL certificates, or any service hosted on the domain. It should only be disabled for the duration of an outbound transfer or a registrant change on TLDs that require it, and re-enabled immediately after. Go to [Lock a domain](https://developer.godaddy.com/docs/api-users/domains/manage/lock) for the API operations to read and toggle the lock state. ## ICANN registrant contact change approval Changing the registrant's email, first name, last name, or organization while WHOIS privacy is disabled triggers the ICANN Contact Change Approval flow. ICANN sends the previous registrant an email asking them to approve the update. The domain stays in a pending state until the old registrant approves the change, or the request auto-expires after 60 days. GoDaddy enables WHOIS privacy on all registrations at no additional cost. Most accounts will not encounter this flow unless privacy was explicitly disabled. Check the `exposeWhoIs` field on the domain object to confirm privacy status. ### What triggers the flow The approval flow activates when **all** of the following conditions are met: * WHOIS privacy is disabled on the domain (`exposeWhoIs: true` in the v1 Domain object) * The `contactRegistrant` update changes at least one of: `nameFirst`, `nameLast`, `email`, or `organization` Changes to `contactAdmin`, `contactBilling`, `contactTech`, or non-identifying fields (phone, address) do not trigger the flow. Go to [Update contacts](https://developer.godaddy.com/docs/api-users/domains/manage/update-contacts#icann-registrant-contact-change-approval) to check or cancel a pending approval through the API. # About the Domains API (https://developer.godaddy.com/en/docs/api-users/domains) --- title: About the Domains API description: >- How the Domains API is structured, what its version namespaces cover, and how the core resources relate to each other. keywords: >- DomainDetail, quoteToken, registration-quotes endpoint, customerId, sso-key deprecation, domain API reference, async polling, Action object related: concepts: - title: Domains core concepts href: /docs/api-users/domains/concepts - title: How GoDaddy APIs work href: /docs/api-users/concepts/how-godaddy-apis-work guides: - title: Search domain availability href: /docs/api-users/domains/search - title: Register a domain href: /docs/api-users/domains/register - title: Manage DNS records href: /docs/api-users/domains/manage/dns --- ## Overview The Domains API covers the full domain registration and management lifecycle: searching availability, registering domains, managing DNS records, updating WHOIS contacts, controlling registry lock, renewing registrations, configuring forwarding, and managing transfers. Operations are distributed across three version namespaces — v3 is the preferred namespace for new integrations, with v1 and v2 covering capabilities not yet migrated. Go to [Domain management concepts](https://developer.godaddy.com/docs/api-users/domains/concepts) for background on registrars, registries, the domain lifecycle, DNS, and WHOIS. ## How the API is structured ### Version namespaces Operations are split across three namespaces that have accumulated over years of product development. Use v3 where available; fall back to v1 or v2 where v3 doesn't cover the operation yet. | Version | Base path | Auth | Primary use | | ------- | ---------------------------------------- | -------------- | ---------------------------------------------------- | | v3 | `/v3/domains/...` | PAT only | Availability, registration, DNS records, nameservers | | v2 | `/v2/customers/{customerId}/domains/...` | PAT or sso-key | Forwarding, transfers, async operations | | v1 | `/v1/domains/...` | PAT or sso-key | List domains, renewals, contacts, lock | v3 endpoints require a Personal Access Token (PAT). The older `sso-key` credential is still accepted on v1 and v2 endpoints but is scheduled for deprecation in 2026. New integrations should use PATs exclusively. v2 endpoints require a `customerId` path parameter. That value is a UUID, not the numeric shopper ID your account settings display. Go to [Find your customer ID](https://developer.godaddy.com/docs/references/rest/domains/v2#find-your-customer-id) for the lookup that returns it. v1 and v3 endpoints identify the caller from the bearer token directly. ### Registration: quote-execute with async polling v3 uses a two-step registration flow that separates pricing from execution — the price you agree to is the price charged. The `quoteToken` returned by the quote endpoint is valid for 10 minutes. Registration is not reversible and charges the account's payment method. Use the `Idempotency-Key` request header on `POST /v3/domains/registrations` to prevent duplicate charges if a request times out or returns an ambiguous error. If the operation status is `EXECUTING`, poll — do not resubmit. ### Async operations Registration is asynchronous — the initial response returns a registration ID, and you poll for completion. Certain v2 operations (transfers, redemption) also return `202 Accepted` with an `Action` body rather than completing synchronously. Poll `GET /v2/customers/{customerId}/domains/actions/{actionId}` until the action reaches a terminal state. | Status | Meaning | | ----------- | ---------------------------------- | | `CONFIRMED` | Accepted, processing | | `EXECUTING` | In progress | | `COMPLETED` | Succeeded | | `FAILED` | Failed — check `error` for details | | `CANCELLED` | Cancelled | Most v1 and v3 write operations complete synchronously and return `204 No Content`. ## Core resources ### Domain The Domain is the central resource. It carries: * Registry metadata: domain name, status (`ACTIVE`, `EXPIRED`, `PENDING_TRANSFER`), expiration timestamp * The four WHOIS contact roles: registrant, admin, billing, tech * Authoritative nameservers * Lock and privacy flags (`locked`, `privacy`) * Renewal state: `renewAuto` flag and `expires` timestamp The schema is named `DomainDetail` in v1 and `DomainDetailV2` in v2. v2 extends v1 with async operation tracking and more consistent status values — for single-domain detail, prefer v2. ### DNS records DNS records are managed under the v3 zone endpoint: `GET`, `POST`, and `DELETE` against `/v3/domains/zones/{zone}/dns-records`. GoDaddy's authoritative nameservers support A, AAAA, CNAME, MX, TXT, SRV, NS, and CAA record types. Changes take effect synchronously on GoDaddy's nameservers. External resolvers cache values for up to the record's TTL (600–86,400 seconds on GoDaddy's authoritative DNS). If you replace the nameservers with those of another DNS provider, the GoDaddy DNS API can no longer manage records for the domain — DNS management moves to the new provider. ### Action (v2 async tracker) Long-running v2 operations return `202 Accepted` with an `Action` object instead of completing synchronously. Poll `GET /v2/customers/{customerId}/domains/actions/{actionId}` until terminal state. The `Action` carries the operation type, current status, and error details on failure. ## Resource relationships ## Operations by task | Task | Version | Guide | | ------------------------- | ------- | ----------------------------------------------------------------- | | Check availability | v3 | [Search domain availability](https://developer.godaddy.com/docs/api-users/domains/search) | | Get suggestions | v3 | [Search domain availability](https://developer.godaddy.com/docs/api-users/domains/search) | | Register a domain | v3 | [Register a domain](https://developer.godaddy.com/docs/api-users/domains/register) | | List registered domains | v1 | [Registered domains](https://developer.godaddy.com/docs/api-users/domains/manage/list) | | Manage DNS records | v3 | [Manage DNS records](https://developer.godaddy.com/docs/api-users/domains/manage/dns) | | Replace nameservers | v3 | [Manage DNS records](https://developer.godaddy.com/docs/api-users/domains/manage/dns) | | Update WHOIS contacts | v1 | [Update contacts](https://developer.godaddy.com/docs/api-users/domains/manage/update-contacts) | | Toggle auto-renew / renew | v1 | [Manage renewals](https://developer.godaddy.com/docs/api-users/domains/manage/renewals) | | Toggle registry lock | v1 | [Lock a domain](https://developer.godaddy.com/docs/api-users/domains/manage/lock) | | Configure forwarding | v2 | [Forward a domain](https://developer.godaddy.com/docs/api-users/domains/manage/forwarding) | | Transfer a domain in | v2 | [Browse the Domains API](https://developer.godaddy.com/docs/api-users/domains/manage) | ## OAuth scopes Request only the scopes your integration needs. Most write operations require a separate scope in addition to `domains.domain:read`. | Scope | What it grants | | ---------------------------- | ------------------------------------------------- | | `domains.domain:read` | Read domains, DNS records, availability checks | | `domains.domain:create` | Register new domains | | `domains.domain:update` | Update settings, contacts, lock state, auto-renew | | `domains.dns:update` | Create and delete DNS records | | `domains.nameserver:update` | Replace authoritative nameservers | | `domains.registration:write` | Transfer domains in | # About Domains pricing (https://developer.godaddy.com/en/docs/api-users/domains/pricing) --- title: About Domains pricing description: >- v3 API domain registrations use a discount pricing model. Indicative prices come from check-availability; the locked price is set by registration-quotes. keywords: >- .com price, domain cost, TLD pricing table, minor currency units, first-term price, auto-renewal rate, discounted rate, registration sale price agentNotes: permissions: - Any account. Registration requires a billing method on file. scopes: - 'domains.domain:read' rateLimit: Standard per-credential limits apply; see Rate limits. idempotent: true destructive: false failureRecovery: >- Prices from check-availability are indicative. Always confirm with POST /v3/domains/registration-quotes. The quoteToken locks the exact price charged. related: guides: - title: Register a domain href: /docs/api-users/domains/register - title: Search for domains href: /docs/api-users/domains/search apis: - title: v3 Registration Quotes href: /docs/references/rest/domains/v3/quote-domain-registration - title: Domains v3 reference href: /docs/references/rest/domains/v3 --- ## Overview The v3 Domains API uses a discount pricing model for top-level domain (TLD) registrations. Registrations are charged at member-level rates with no membership fee, no API access fee, and no limit on the number of domains you can register. Auto-renewals use the same rates. Discounted rates apply only to purchases made through the v3 API. Purchases through v1 or v2, or through the GoDaddy retail site, are charged at standard rates. Any account with a billing method on file qualifies. Discounted rates apply from your first registration on the v3 API, with no volume thresholds, so you can secure a domain for anything you build, no matter the scale. This page explains how the pricing model works. For step-by-step procedures, go to [Search domain availability](https://developer.godaddy.com/docs/api-users/domains/search) to check prices before committing and [Register a domain](https://developer.godaddy.com/docs/api-users/domains/register) to lock a price and execute a purchase. ## How pricing works v3 pricing has two stages: indicative and locked. The availability check and suggestions endpoints return indicative pricing. It reflects the likely price for a registration and is suitable for displaying to users before they commit. It's not a price guarantee. Rates can change between when you search and when you purchase. Locked pricing is set when you call `POST /v3/domains/registration-quotes`. The API returns a `quoteToken` that pins the exact price. The price in the token is the price charged at registration. The token expires after a short window. If it expires before you execute, request a new quote. Go to [Search domain availability](https://developer.godaddy.com/docs/api-users/domains/search) for the full check-availability procedure, or [Register a domain](https://developer.godaddy.com/docs/api-users/domains/register) for the complete quote-execute flow. ## TLD coverage Discounted rates apply to the top TLDs. The following table illustrates the discounted rates in USD: | TLD | Registration (1 yr) | Auto-renewal (1 yr) | Standard renewal | | ------- | ------------------- | ------------------- | ---------------- | | .com | $9.79 | $14.99 | $22.99 | | .org | $7.49 | $15.99 | $23.99 | | .net | $11.65 | $16.99 | $24.99 | | .info | $2.99 | $29.99 | $41.99 | | .biz | $5.99 | $25.99 | $35.99 | | .cc | $3.49 | $11.99 | $15.99 | | .co | $8.99 | $42.99 | $59.99 | | .us | $3.99 | $11.99 | $19.99 | | .ca | $7.29 | $13.99 | $17.99 | | .au | $6.69 | $11.99 | $14.99 | | .com.au | $6.69 | $11.99 | $14.99 | | .uk | $4.99 | $9.99 | $12.99 | | .co.uk | $4.99 | $9.99 | $12.99 | | .io | $29.99 | $69.99 | $89.99 | | .tv | $24.99 | $35.99 | $49.99 | | .app | $7.99 | $19.99 | $27.99 | | .club | $2.49 | $20.99 | $29.99 | | .xyz | $0.99 | $18.99 | $25.99 | | .vip | $3.99 | $14.99 | $23.99 | | .ai | $159.98 (2 yr) | $239.98 (2 yr) | $319.98 | .ai requires a 2-year minimum term. Registration and auto-renewal discounts are only available in 2-year increments. The prices shown are per 2-year period, not per year. Premium domains are excluded from discounted pricing. API responses express prices in minor currency units. A value of `1049` means $10.49. Divide by 100 for the display price. ## Renewal pricing Auto-renew is on by default and charges the discounted renewal price shown in your registration quote. If you renew manually (either through a renewal API call or the GoDaddy account UI), the renewal is charged at the standard rate. To retain the discounted rate, keep auto-renew enabled. You can manage auto-renew per domain in [domain settings](https://developer.godaddy.com/docs/api-users/domains/manage). To lock pricing for multiple years, purchase a multi-year term upfront. Year 1 is charged at the registration sale price. Subsequent years are charged at the discounted renewal price. ## Refunds GoDaddy’s standard [Refund Policy](https://www.godaddy.com/legal/agreements/refund-policy) applies to API purchases. The quote-then-execute flow means nothing is charged until the registration request is executed using a valid `quoteToken`. The price in the `quoteToken` is the price charged. Go to [Register a domain](https://developer.godaddy.com/docs/api-users/domains/register) for the full registration flow. ## Terms Use of the Domains API and domain purchases are subject to GoDaddy’s [API Terms of Use](https://www.godaddy.com/legal/agreements/godaddy-api-terms-of-use) and [API Domain Purchase Agreement](https://www.godaddy.com/legal/agreements/api-domain-purchase-agreement). # About the Email API (https://developer.godaddy.com/en/docs/api-users/email) --- title: About the Email API description: >- How the Email API is structured, how mailbox provisioning works, and how the core resources relate to each other. keywords: >- mailbox provisioning, Titan email, mailboxId, check-mailbox-eligibility, Idempotency-Key, email hosting API, provision mailbox, list mailboxes related: apis: - title: Email API — Mailboxes href: /docs/references/rest/email/list-mailboxes guides: - title: Provision a mailbox href: /docs/api-users/email/mailboxes/provision-mailboxes - title: List and look up mailboxes href: /docs/api-users/email/mailboxes/manage-mailboxes concepts: - title: Authentication href: /docs/api-users/auth - title: Handle errors href: /docs/api-users/errors --- ## Overview The Email API provisions and manages email mailboxes for domains owned by the authenticated account. All paths are under `/v1/email/`, and every operation is scoped to domains the calling account already owns. There's no separate step to associate a domain first. The API exposes a single core resource, `Mailbox`, plus an eligibility check that tells you whether a mailbox can be provisioned for a given address before you attempt to create one. ## How mailbox creation works Creating a mailbox is asynchronous. `POST /v1/email/mailboxes` returns `202 Accepted` with the mailbox in its initial state (`status: EXECUTING`). Poll `GET /v1/email/mailboxes/{mailboxId}` until `status` reaches `COMPLETED` or `FAILED`. `EXECUTING`, `COMPLETED`, `FAILED`, and `DELETED` are the valid statuses for a mailbox. Go to [Provision a mailbox](https://developer.godaddy.com/docs/api-users/email/mailboxes/provision-mailboxes) for the full polling procedure. ## The Mailbox object The following table describes the fields of the `Mailbox` object: | Field | Description | Note | | ------------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | `mailboxId` | Unique identifier for the mailbox. | Returned from `POST /v1/email/mailboxes`, used as the path parameter on `GET /v1/email/mailboxes/{mailboxId}`. | | `emailAddress` | Mailbox email address. | | | `mailboxType` | Underlying email platform. | For example, `TITAN`. Auto-selected from the domain's entitlements at creation (you don't choose it). | | `firstName` / `lastName` | Mailbox owner's name. | | | `displayName` | Display name shown to recipients. | | | `status` | Provisioning status. | `EXECUTING`, `COMPLETED`, `FAILED`, or `DELETED`. | | `createdAt` / `updatedAt` | ISO 8601 timestamps. | | | `links` | Hypermedia links related to the mailbox, including `self`. | | ## Eligibility, entitlements, and consents Before the platform can provision a mailbox, three conditions must align. The address must be eligible, the account must have an entitlement (a provisioning credit tied to the domain), and any requirements on that entitlement must be consented to. Call `GET /v1/email/check-mailbox-eligibility` to evaluate all three before attempting `POST /v1/email/mailboxes`. The response is an `EligibilityResult`: | Field | Description | Note | | ------------------ | --------------------------------------------------------------- | ------------------------------------------------------------------------------- | | `isEligible` | Whether a mailbox can be provisioned for the requested address. | When `false`, the API returns an error response with details. | | `eligibleAccounts` | Entitlements available to provision with. | Each entry has `accountId`, `mailboxType`, `accountName`, and a `default` flag. | An entitlement might carry `requirements` (conditions the caller must accept before provisioning). A free-trial entitlement, for example, might require `FREETRIAL_AUTORENEW` consent. Pass any requirements as `consents` in the `POST /v1/email/mailboxes` request body. The created mailbox includes the accepted consents as `agreements`. Go to [Provision a mailbox](https://developer.godaddy.com/docs/api-users/email/mailboxes/provision-mailboxes) for the full request and response shapes. ## OAuth scopes The following table lists the OAuth scopes required for managing email mailboxes. Request only the scopes your integration needs. | Scope | What it grants | | ---------------------- | ---------------------------------------------------------------------- | | `email.mailbox:read` | List email mailboxes for domains owned by the authenticated account. | | `email.mailbox:create` | Create email mailboxes for domains owned by the authenticated account. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for how to generate a PAT with these scopes. # Node.js app requirements (https://developer.godaddy.com/en/docs/api-users/hosting/app-requirements) --- title: Node.js app requirements description: >- The structure and configuration a Node.js app must have before uploading to GoDaddy Hosting. keywords: >- package.json, build script, start script, process.env.PORT, node_modules, dependencies, devDependencies, zip requirements, deploy requirements, hosting requirements, node version, engines related: guides: - title: How to deploy your Node.js app href: /docs/api-users/hosting/workflows/deploy-nodejs-app concepts: - title: Hosting core concepts href: /docs/api-users/hosting/concepts --- ## Overview This page describes the structure your Node.js app must have before you upload it to GoDaddy Hosting. An app that skips any of these requirements fails at build or startup when you publish. Go to [How to deploy your Node.js app](https://developer.godaddy.com/docs/api-users/hosting/workflows/deploy-nodejs-app) for the full deployment walkthrough. ## package.json The zip must contain a `package.json` at the root. It must include non-empty `name` and `version` fields. The `main` field is optional but recommended when your entry point differs from `index.js`. Specifying a Node.js version is also recommended: ```json { "name": "my-app", "version": "1.0.0", "engines": { "node": "20.x" } } ``` ## Scripts `package.json` must define both a `build` script and a `start` script. **Build script:** The platform runs `npm run build` during deployment. If your app has no compile step, define a no-op placeholder: ```json "build": "echo build" ``` Frameworks (Next.js, NestJS, TypeScript projects) need a real build command. **Start script:** The platform starts your app with `npm start`. The command must point to a file that exists in the zip: ```json "start": "node index.js" ``` A complete minimal `package.json`: ```json { "name": "my-app", "version": "1.0.0", "engines": { "node": "20.x" }, "scripts": { "build": "echo build", "start": "node index.js" } } ``` ## Port binding Your app must listen on the port the platform assigns. Read it from `process.env.PORT`: ```js const port = process.env.PORT || 3000; server.listen(port); ``` The platform sets `PORT` at runtime. An app that binds to a hardcoded port won't receive traffic. ## Dependencies Every package the app needs at runtime must be in `dependencies`, not `devDependencies`. The platform installs only `dependencies` before running build and start. ```json { "dependencies": { "express": "^4.18.0" }, "devDependencies": { "jest": "^29.0.0" } } ``` A runtime package left in `devDependencies` causes `MODULE_NOT_FOUND` errors at startup. ## Zip contents Include source files and `package.json`, but exclude `node_modules`. The platform runs `npm install` after extracting the zip. Files to include and exclude: | Include | Exclude | | ----------------------------------- | --------------------------- | | `package.json`, `package-lock.json` | `node_modules/` | | All source files | `.env` files with secrets | | Static assets | Uncommitted build artifacts | Including `node_modules` in the zip slows upload and might conflict with the platform install. # How to attach or remove a domain (https://developer.godaddy.com/en/docs/api-users/hosting/attach-domain) --- title: How to attach or remove a domain description: Attach a custom domain to your hosted app. keywords: >- PUT /apps/{appId}/domains, custom domain, attach domain, DNS, domain configuration, hosting.domain:write agentNotes: scopes: - 'hosting.domain:write' idempotent: false destructive: false failureRecovery: >- A 409 means the domain is already attached — treat as success. Otherwise verify you own the domain and it is not in use by another app. related: guides: - title: Deploy your Node.js app href: /docs/api-users/hosting/workflows/deploy-nodejs-app - title: Manage apps href: /docs/api-users/hosting/manage-apps - title: Attach to a hosting plan href: /docs/api-users/hosting/attach-hosting-plan concepts: - title: Hosting concepts href: /docs/api-users/hosting/concepts apis: - title: Hosting API reference href: /docs/references/rest/hosting --- ## Overview After you deploy your app, you can attach a custom domain to make it accessible through a friendly URL instead of the default hosting domain. Domain attachment is optional and your app is fully functional without it. Only domains you own can be attached to your app. After attachment, traffic to that domain routes to your hosted application. For the domain to route correctly to your app, your domain's DNS must point to GoDaddy's hosting infrastructure. If registered with GoDaddy, this is often automatic. For other registrars, update your domain's nameservers or DNS records accordingly. Go to [Deploy your Node.js app](https://developer.godaddy.com/docs/api-users/hosting/workflows/deploy-nodejs-app) for the core deployment flow. Domain attachment happens after your app is live. ## Prerequisites The following prerequisites are required before you can attach a domain to your app: * a [Personal Access Token](https://developer.godaddy.com/personal-access-token) with the `hosting.domain:write` scope * a deployed app Go to [Deploy your Node.js app](https://developer.godaddy.com/docs/api-users/hosting/workflows/deploy-nodejs-app) for more information on deploying an app. * a domain you own (already registered with GoDaddy or another registrar) ## Attach a domain to an app `POST /apps/{appId}/domains` attaches a domain to your app and initiates DNS verification. Returns `202 Accepted` with a domain attachment and enters DNS verification. DNS propagation can take a few minutes and your app is accessible at the domain after DNS resolves. * Attach the domain: ```bash tab="curl" curl -s -X POST "$BASE_URL/v1/hosting/apps/$APP_ID/domains" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "Content-Type: application/json" \ -d '{ "hostname": "my-app.example.com" }' ``` ```js tab="Node" const res = await fetch(`${process.env.BASE_URL}/v1/hosting/apps/${appId}/domains`, { method: 'POST', headers: { Authorization: `Bearer ${process.env.GODADDY_PAT}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ hostname: 'my-app.example.com' }), }); if (!res.ok) { console.error(`Error: ${res.status}`); return; } const result = await res.json(); console.log('Domain attachment initiated', result); ``` ```python tab="Python" import requests, os resp = requests.post( f"{os.environ['BASE_URL']}/v1/hosting/apps/{app_id}/domains", headers={"Authorization": f"Bearer {os.environ['GODADDY_PAT']}"}, json={"hostname": "my-app.example.com"}, ) if resp.status_code != 202: print(f"Error: {resp.status_code}") exit(1) result = resp.json() print("Domain attachment initiated", result) ``` ```go tab="Go" body := strings.NewReader(`{"hostname":"my-app.example.com"}`) req, _ := http.NewRequest("POST", os.Getenv("BASE_URL")+"/v1/hosting/apps/"+appID+"/domains", body) req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT")) req.Header.Set("Content-Type", "application/json") resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() if resp.StatusCode != 202 { fmt.Printf("Error: %d\n", resp.StatusCode) return } // decode resp.Body to get result var result map[string]interface{} json.NewDecoder(resp.Body).Decode(&result) fmt.Println("Domain attachment initiated", result) ``` ## Remove a domain To remove a domain attachment, use `DELETE /apps/{appId}/domains/{domainId}`. This detaches the domain from the app but does not modify DNS records at your registrar. * Remove a domain: ```bash tab="curl" curl -s -X DELETE "$BASE_URL/v1/hosting/apps/$APP_ID/domains/$DOMAIN_ID" \ -H "Authorization: Bearer $GODADDY_PAT" ``` ```js tab="Node" const res = await fetch(`${process.env.BASE_URL}/v1/hosting/apps/${appId}/domains/${domainId}`, { method: 'DELETE', headers: { Authorization: `Bearer ${process.env.GODADDY_PAT}` }, }); ``` ```python tab="Python" resp = requests.delete( f"{os.environ['BASE_URL']}/v1/hosting/apps/{app_id}/domains/{domain_id}", headers={"Authorization": f"Bearer {os.environ['GODADDY_PAT']}"}, ) ``` ```go tab="Go" req, _ := http.NewRequest("DELETE", os.Getenv("BASE_URL")+"/v1/hosting/apps/"+appID+"/domains/"+domainID, nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT")) resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() ``` Success returns `204 No Content`. ## Common errors The following table lists common errors when attaching a domain: | Status | Cause | Action | | ------ | ---------------------------------------- | -------------------------------------------------------------------------------------------------------- | | `400` | Invalid domain format | Verify the domain is a valid FQDN (e.g., `my-app.example.com`) | | `401` | Expired or revoked PAT, or missing scope | Go to [Hosting core concepts](https://developer.godaddy.com/docs/api-users/hosting/concepts#scopes-reference) for the scopes you need | | `404` | App not found | Verify the app ID is correct | | `409` | Domain already in use | The domain is already attached to this app or another app on your account | # How to attach an app to a hosting plan (https://developer.godaddy.com/en/docs/api-users/hosting/attach-hosting-plan) --- title: How to attach an app to a hosting plan description: Attach your app to a web hosting subscription to enable publishing. keywords: >- PUT /apps/{appId}/subscription, attach app subscription, hosting plan, web hosting, hosting.subscription:write agentNotes: scopes: - 'hosting.subscription:write' idempotent: true destructive: false failureRecovery: >- Attachment is synchronous. Verify the subscription ID exists on your account and the app is already created. related: tutorials: - title: Deploy your Node.js app href: /docs/api-users/hosting/workflows/deploy-nodejs-app guides: - title: Manage apps href: /docs/api-users/hosting/manage-apps concepts: - title: Hosting concepts href: /docs/api-users/hosting/concepts apis: - title: Hosting API reference href: /docs/references/rest/hosting --- ## Overview Subscription attachment is required before going live for Node.js apps. Before you can publish a Node.js app to production, you must attach it to a web hosting subscription. This operation is synchronous and returns immediately on success. Subscriptions are purchased separately in your GoDaddy account. After attachment, the app is bound to that subscription's infrastructure and billing. This article describes how to attach a hosting plan to your web app. Go to [Deploy your Node.js app](https://developer.godaddy.com/docs/api-users/hosting/workflows/deploy-nodejs-app) for the full deployment walkthrough (which includes this procedure). ## Prerequisites The following prerequisites are required before you can attach a hosting plan to your app: * a [Personal Access Token](https://developer.godaddy.com/personal-access-token) with the `hosting.subscription:write` scope * a hosting app already created Go to [Deploy your Node.js app](https://developer.godaddy.com/docs/api-users/hosting/workflows/deploy-nodejs-app) for instructions to create a hosting app. * a web hosting subscription ID from your GoDaddy account ## Attach an app to a subscription `PUT /apps/{appId}/subscription` attaches a created app to a hosting plan. The subscription must belong to your account and have available capacity. Success returns `200 OK` with the subscription attachment details. After you complete this procedure, you can publish your app. * Attach the app: ```bash tab="curl" curl -s -X PUT "$BASE_URL/v1/hosting/apps/$APP_ID/subscription" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "Content-Type: application/json" \ -d '{ "subscriptionId": "'$SUBSCRIPTION_ID'" }' ``` ```js tab="Node" const res = await fetch(`${process.env.BASE_URL}/v1/hosting/apps/${appId}/subscription`, { method: 'PUT', headers: { Authorization: `Bearer ${process.env.GODADDY_PAT}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ subscriptionId }), }); if (!res.ok) { console.error(`Error: ${res.status}`); return; } const result = await res.json(); console.log('Attachment successful', result); ``` ```python tab="Python" import requests, os resp = requests.put( f"{os.environ['BASE_URL']}/v1/hosting/apps/{app_id}/subscription", headers={"Authorization": f"Bearer {os.environ['GODADDY_PAT']}"}, json={"subscriptionId": subscription_id}, ) if resp.status_code != 200: print(f"Error: {resp.status_code}") exit(1) result = resp.json() print("Attachment successful", result) ``` ```go tab="Go" body := strings.NewReader(`{"subscriptionId":"` + subscriptionID + `"}`) req, _ := http.NewRequest("PUT", os.Getenv("BASE_URL")+"/v1/hosting/apps/"+appID+"/subscription", body) req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT")) req.Header.Set("Content-Type", "application/json") resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() if resp.StatusCode != 200 { fmt.Printf("Error: %d\n", resp.StatusCode) return } var result map[string]interface{} json.NewDecoder(resp.Body).Decode(&result) fmt.Println("Attachment successful", result) ``` ## Common errors The following table lists common errors when attaching: | Status | Cause | Action | | ------ | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | `400` | Invalid app ID or subscription ID | Verify both IDs are correct and belong to your account | | `401` | Expired or revoked PAT, or missing scope | Go to [Hosting core concepts](https://developer.godaddy.com/docs/api-users/hosting/concepts#scopes-reference) for the scopes you need | | `404` | App or subscription not found | Confirm the app exists and the subscription ID is on your account | | `409` | No capacity available on the subscription | The subscription has no available capacity. Verify the subscription supports additional apps or contact GoDaddy support | # Hosting core concepts (https://developer.godaddy.com/en/docs/api-users/hosting/concepts) --- title: Hosting core concepts description: >- Variants, deployments, async jobs, and secrets: the mental model behind the Hosting API. keywords: >- preview variant, publish variant, async job polling, terminal states active failed, deployment snapshot, batch secret operations, idempotency key, hosting model related: tutorials: - title: Deploy your Node.js app href: /docs/api-users/hosting/workflows/deploy-nodejs-app guides: - title: Manage secrets href: /docs/api-users/hosting/manage-secrets - title: Read logs href: /docs/api-users/hosting/read-logs apis: - title: Hosting API reference href: /docs/references/rest/hosting --- ## Overview This page explains the mental model behind the Hosting API. Three concepts run through all resource groups: variants, async jobs, and deployments. Understanding these makes the rest of the surface readable on first contact. The Hosting API supports Node.js apps. Other product types are coming in future releases. Go to [Deploy your Node.js app](https://developer.godaddy.com/docs/api-users/hosting/workflows/deploy-nodejs-app) for a hands-on walkthrough. Go to the [Hosting API reference](https://developer.godaddy.com/docs/references/rest/hosting) for endpoint details. ## Variants Every hosted app needs a way to test a change without exposing it to the traffic your users are already hitting. The Hosting API solves this by giving every app two parallel runtime copies, called variants, instead of leaving you to provision and wire up separate staging and production environments yourself. Each variant has its own source, its own secrets, and its own URL. Both belong to the same app and share the same id. The following table describes the two variants: | Variant | Description | Typical use | | --------- | ------------------------------------------------------------- | ---------------------------------------- | | `preview` | Working copy. Receives new source uploads and secret changes. | Iteration, integration testing, staging. | | `publish` | Production copy. Serves live traffic. | Whatever your users actually hit. | Uploads land on `preview`. **Publishing** promotes the current preview to `publish`. Only the next upload overwrites `preview`. Per-variant reads differ by endpoint. `GET /v1/hosting/apps/{appId}/status` returns both variants in one response with no filter parameter. `GET /v1/hosting/apps/{appId}/secrets` accepts an optional `variant` query parameter. `GET /v1/hosting/apps/{appId}/logs` accepts an optional `variant` query parameter (`PREVIEW` or `PUBLISH`, defaults to `PREVIEW`), plus optional filters for `source` (stream), `level` (severity), and `since` (timestamp). Secret writes take `variant` in the request body. ## Async jobs Operations that outlive a single request return immediately with a job or deployment record. Poll a status endpoint until they reach a terminal state. The following diagram shows the create-app polling sequence: ### Terminal states The following table lists the terminal states for each job type and the endpoint to poll: | Job type | Poll endpoint | Terminal states | | ------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | Create app | `GET /v1/hosting/app-operations/{operationId}` | `COMPLETED` (ready), `FAILED` | | Source import | `GET /v1/hosting/apps/{appId}/imports/{importId}` | `COMPLETED`, `FAILED` | | Publish | `GET /v1/hosting/apps/{appId}/deployments/{deploymentId}` and `GET /v1/hosting/apps/{appId}/status` | Latest deployment reaches `COMPLETED`; then inspect `variants` on the status response for the affected environment | ### Polling guidance The following list provides guidance for polling async jobs: * **Interval:** two to five seconds is a good starting point. Back off on longer jobs. * **Give-up window:** most create and upload jobs complete in under a minute. If you're still in `pending` after five minutes, treat it as stuck and surface an error. * **Idempotency:** re-polling is free. The status endpoints have no side effects. * **Idempotency-Key header:** Include `Idempotency-Key: ` on mutation requests (POST, PATCH) to make retries safe. If the server receives a duplicate request with the same key, it returns the original response without creating a duplicate resource. ## Deployments A deployment is a snapshot of source + config that ran (or is running). Each deployment has a sequential number and persists indefinitely. Even after publish overwrites the live one, older deployments remain in the history. The following calls create and list deployments: ``` POST /v1/hosting/apps/{appId}/imports # upload zip → job → new source on preview POST /v1/hosting/apps/{appId}/deployments # publish preview → new deployment on publish GET /v1/hosting/apps/{appId}/deployments # history (paginate with limit, default 20, max 50) ``` Runtime status (`GET /v1/hosting/apps/{appId}/status`) is a separate concern from deployments. It tells you whether the variant is actually up and serving, independent of what deployment it points at. ## Secrets You configure secrets per variant using a standard [RFC 6902 JSON Patch](https://datatracker.ietf.org/doc/html/rfc6902) array. Pass the environment as the `variant` query parameter (`PREVIEW` or `PUBLISH`). Each path is `/{SECRET_NAME}`. A single PATCH request can add, replace, or remove secrets. The combined total must not exceed 50 operations per request. The following request body shows all three operation types in one call: ```json [ { "op": "add", "path": "/STRIPE_KEY", "value": "sk_live_abc1234" }, { "op": "replace", "path": "/DB_URL", "value": "postgres://db.example.com/mydb" }, { "op": "remove", "path": "/OLD_FLAG" } ] ``` The response contains metadata only (like names and last-updated timestamps). No endpoint returns secret values, including reads. If you need to know the value of a secret, look it up in whatever system generated it. ## Putting it together The following diagram shows the full iteration loop across variants: Every step above is a single API call plus polling. That's the whole model. For the end-to-end deploy walkthrough, go to [Deploy your Node.js app](https://developer.godaddy.com/docs/api-users/hosting/workflows/deploy-nodejs-app). For endpoints, go to the [Hosting API reference](https://developer.godaddy.com/docs/references/rest/hosting). ## Scopes reference Every Hosting API operation requires a specific scope on your Personal Access Token (PAT). Select only the scopes your integration needs. Narrower tokens are easier to reason about when something goes wrong. Go to [Personal Access Tokens](https://developer.godaddy.com/personal-access-token) to create or update a token. The following table describes each scope and what it unlocks: | Scope | What it unlocks | | ---------------------------- | ------------------------------------ | | `hosting.application:read` | Read application details | | `hosting.application:create` | Create new applications | | `hosting.application:update` | Update application settings | | `hosting.application:delete` | Delete applications | | `hosting.deployment:execute` | Trigger deployments and restarts | | `hosting.source:read` | Read source import status | | `hosting.source:write` | Upload or link source code | | `hosting.secret:read` | List application secrets | | `hosting.secret:write` | Create or update application secrets | | `hosting.log:read` | Read application logs | | `hosting.domain:read` | Read attached domains | | `hosting.domain:write` | Attach or remove domains | | `hosting.subscription:read` | Read subscription data | | `hosting.subscription:write` | Attach subscriptions to applications | # About the Hosting API (https://developer.godaddy.com/en/docs/api-users/hosting) --- title: About the Hosting API description: >- Deploy and operate apps on GoDaddy's hosting platform via a REST API. Preview and publish with no dashboard required. Supports Node.js apps. keywords: >- PREVIEW PUBLISH environment, POST /v1/hosting/apps, POST /v1/hosting/apps/{appId}/imports, POST /v1/hosting/apps/{appId}/deployments, operation polling, hosting scopes, zip bundle upload, deployment, app lifecycle, attach hosting plan full: true related: tutorials: - title: Deploy your Node.js app href: /docs/api-users/hosting/workflows/deploy-nodejs-app guides: - title: Manage apps href: /docs/api-users/hosting/manage-apps - title: Manage secrets href: /docs/api-users/hosting/manage-secrets - title: Read logs href: /docs/api-users/hosting/read-logs - title: Attach to a hosting plan href: /docs/api-users/hosting/attach-hosting-plan - title: Attach domain href: /docs/api-users/hosting/attach-domain - title: Troubleshoot Hosting href: /docs/api-users/troubleshoot/hosting concepts: - title: Hosting core concepts href: /docs/api-users/hosting/concepts apis: - title: Hosting API reference href: /docs/references/rest/hosting --- ## Overview The Hosting API is a REST API for deploying and operating apps on GoDaddy's hosted platform. It covers the full app lifecycle: create an app, attach to a hosting plan, upload source as a zip, publish to production, manage secrets per variant, and read logs. The API is async-first. Most write operations return immediately with a job or deployment record, and you poll a status endpoint until the operation completes. The Hosting API supports Node.js apps. Other runtimes are coming in future releases. Go to [Deploy your Node.js app](https://developer.godaddy.com/docs/api-users/hosting/workflows/deploy-nodejs-app) for the initial deploy walkthrough. Go to [Hosting concepts](https://developer.godaddy.com/docs/api-users/hosting/concepts) for the variant and deployment model. ## What you can do The following table lists each guide and what it covers: | Guide | Description | | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- | | [Deploy your Node.js app](https://developer.godaddy.com/docs/api-users/hosting/workflows/deploy-nodejs-app) | Deploy your app end to end. Create, attach to a hosting plan, upload, publish, and verify in one walkthrough. | | [Manage apps](https://developer.godaddy.com/docs/api-users/hosting/manage-apps) | List, update, and delete apps after the initial deploy. | | [Manage secrets](https://developer.godaddy.com/docs/api-users/hosting/manage-secrets) | Add, update, and delete per-variant environment secrets. Values are write-only. | | [Read logs](https://developer.godaddy.com/docs/api-users/hosting/read-logs) | Fetch application logs by environment, source stream, and time range. | | [Attach to a hosting plan](https://developer.godaddy.com/docs/api-users/hosting/attach-hosting-plan) | Attach a Node.js app to a web hosting subscription (required before going live). | | [Attach domain](https://developer.godaddy.com/docs/api-users/hosting/attach-domain) | Attach a custom domain to your app (optional). | Connecting a GitHub repository through the Hosting API is in development for Node.js apps. You can connect a repository in the web UI and deploy from it, or upload source as a zip. ## Two variants per app Every app has a **preview** variant for iteration and a **publish** variant for production. Uploads and secret changes land on `preview` first; **publish** promotes the current preview to the production variant. Go to [Hosting concepts](https://developer.godaddy.com/docs/api-users/hosting/concepts) for the full model. ## Async by default Long-running operations return immediately with a job or deployment record. Poll the matching status endpoint until the operation reaches a terminal state: * `POST /v1/hosting/apps` → poll `GET /v1/hosting/app-operations/{operationId}` * `POST /v1/hosting/apps/{appId}/imports` → poll `GET /v1/hosting/apps/{appId}/imports/{importId}` * `POST /v1/hosting/apps/{appId}/deployments` → poll `GET /v1/hosting/apps/{appId}/deployments/{deploymentId}` and `GET /v1/hosting/apps/{appId}/status` # How to manage Apps (https://developer.godaddy.com/en/docs/api-users/hosting/manage-apps) --- title: How to manage Apps description: 'List, update, and delete hosting apps using the REST API.' keywords: >- GET /v1/hosting/apps, PATCH /apps/{appId}, DELETE /apps/{appId}, list apps, update app metadata, delete app, hosting.application:update, hosting.application:delete agentNotes: scopes: - 'hosting.application:read' - 'hosting.application:update' - 'hosting.application:delete' destructive: true failureRecovery: >- List and read operations are safe to retry. Deletes are irreversible — confirm the app id before submitting. related: tutorials: - title: Deploy your Node.js app href: /docs/api-users/hosting/workflows/deploy-nodejs-app guides: - title: Manage secrets href: /docs/api-users/hosting/manage-secrets concepts: - title: Hosting concepts href: /docs/api-users/hosting/concepts apis: - title: Apps reference href: /docs/references/rest/hosting/list-apps --- ## Overview This page covers managing your deployed apps: listing all apps, reading a single app, updating its metadata, and deleting it. These operations use the `hosting.application:read`, `hosting.application:update`, and `hosting.application:delete` scopes. Go to [Deploy your Node.js app](https://developer.godaddy.com/docs/api-users/hosting/workflows/deploy-nodejs-app) for the initial create-and-deploy flow. Go to [Hosting core concepts](https://developer.godaddy.com/docs/api-users/hosting/concepts#scopes-reference) for the scopes you need. ## Prerequisites The following prerequisites are required before you can manage your apps: * a [Personal Access Token](https://developer.godaddy.com/personal-access-token) with the `hosting.application:read` scope (all operations), plus `hosting.application:update` or `hosting.application:delete` as needed ## List apps `GET /apps?appType=NODEJS` returns all Node.js apps for your account. The following procedure lists all apps. * List all Node.js apps: ```bash tab="curl" curl -s "$BASE_URL/v1/hosting/apps?appType=NODEJS" \ -H "Authorization: Bearer $GODADDY_PAT" | jq . ``` ```js tab="Node" const res = await fetch(`${process.env.BASE_URL}/v1/hosting/apps?appType=NODEJS`, { headers: { Authorization: `Bearer ${process.env.GODADDY_PAT}` }, }); const apps = await res.json(); ``` ```python tab="Python" import requests, os resp = requests.get( f"{os.environ['BASE_URL']}/v1/hosting/apps", params={"appType": "NODEJS"}, headers={"Authorization": f"Bearer {os.environ['GODADDY_PAT']}"}, ) apps = resp.json() ``` ```go tab="Go" req, _ := http.NewRequest("GET", os.Getenv("BASE_URL")+"/v1/hosting/apps?appType=NODEJS", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT")) resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() ``` The response is an array of app objects. Each includes the app id, name, creation status, and variant details. ## Read an app `GET /apps/{appId}` returns the full record for a single app. The following procedure reads a specific app. * Read the app: ```bash tab="curl" curl -s "$BASE_URL/v1/hosting/apps/$APP_ID" \ -H "Authorization: Bearer $GODADDY_PAT" | jq . ``` ```js tab="Node" const res = await fetch(`${process.env.BASE_URL}/v1/hosting/apps/${appId}`, { headers: { Authorization: `Bearer ${process.env.GODADDY_PAT}` }, }); const app = await res.json(); ``` ```python tab="Python" resp = requests.get( f"{os.environ['BASE_URL']}/v1/hosting/apps/{app_id}", headers={"Authorization": f"Bearer {os.environ['GODADDY_PAT']}"}, ) app = resp.json() ``` ```go tab="Go" req, _ := http.NewRequest("GET", os.Getenv("BASE_URL")+"/v1/hosting/apps/"+appID, nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT")) resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() ``` ## Update app metadata `PATCH /apps/{appId}` updates the app's name or root path. The operation is synchronous and returns `200` with the updated app object. The following procedure updates the app name. * Update the app name: ```bash tab="curl" curl -s -X PATCH "$BASE_URL/v1/hosting/apps/$APP_ID" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "Content-Type: application/json-patch+json" \ -d '[{"op":"replace","path":"/name","value":"my-renamed-app"}]' | jq . ``` ```js tab="Node" const res = await fetch(`${process.env.BASE_URL}/v1/hosting/apps/${appId}`, { method: 'PATCH', headers: { Authorization: `Bearer ${process.env.GODADDY_PAT}`, 'Content-Type': 'application/json-patch+json', }, body: JSON.stringify([{ op: 'replace', path: '/name', value: 'my-renamed-app' }]), }); const updated = await res.json(); ``` ```python tab="Python" resp = requests.patch( f"{os.environ['BASE_URL']}/v1/hosting/apps/{app_id}", headers={ "Authorization": f"Bearer {os.environ['GODADDY_PAT']}", "Content-Type": "application/json-patch+json", }, data='[{"op":"replace","path":"/name","value":"my-renamed-app"}]', ) updated = resp.json() ``` ```go tab="Go" body := strings.NewReader(`[{"op":"replace","path":"/name","value":"my-renamed-app"}]`) req, _ := http.NewRequest("PATCH", os.Getenv("BASE_URL")+"/v1/hosting/apps/"+appID, body) req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT")) req.Header.Set("Content-Type", "application/json-patch+json") resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() ``` ## Delete an app Deleting an app removes both variants and all associated deployments, secrets, and logs. This can't be undone. `DELETE /apps/{appId}` removes the app. The response is `204 No Content` on success. The following procedure deletes an app. * Delete the app: ```bash tab="curl" curl -s -X DELETE "$BASE_URL/v1/hosting/apps/$APP_ID" \ -H "Authorization: Bearer $GODADDY_PAT" ``` ```js tab="Node" await fetch(`${process.env.BASE_URL}/v1/hosting/apps/${appId}`, { method: 'DELETE', headers: { Authorization: `Bearer ${process.env.GODADDY_PAT}` }, }); ``` ```python tab="Python" requests.delete( f"{os.environ['BASE_URL']}/v1/hosting/apps/{app_id}", headers={"Authorization": f"Bearer {os.environ['GODADDY_PAT']}"}, ) ``` ```go tab="Go" req, _ := http.NewRequest("DELETE", os.Getenv("BASE_URL")+"/v1/hosting/apps/"+appID, nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT")) http.DefaultClient.Do(req) ``` ## Common errors The following table lists common errors and recommended actions: | Status | Cause | Action | | ------ | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | `401` | Expired or revoked PAT, or missing scope | Go to [Hosting core concepts](https://developer.godaddy.com/docs/api-users/hosting/concepts#scopes-reference) for the scopes you need | | `403` | Insufficient scope | Verify the token includes `hosting.application:update` or `hosting.application:delete` for write operations | | `404` | App id not found | Confirm the id from `GET /apps` | | `429` | Rate limit exceeded | Back off and retry. Go to [Rate limits](https://developer.godaddy.com/docs/api-users/rate-limits) for handling guidance | # How to manage secrets (https://developer.godaddy.com/en/docs/api-users/hosting/manage-secrets) --- title: How to manage secrets description: 'Add, update, and delete per-variant environment secrets for a hosting app.' keywords: >- PATCH /apps/{appId}/secrets, GET /apps/{appId}/secrets, secret:write scope, per-variant secrets, batch secret operations, preview publish secrets, environment variables hosting agentNotes: scopes: - 'hosting.secret:read' - 'hosting.secret:write' idempotent: false destructive: true failureRecovery: >- The secrets write endpoint is not idempotent. Duplicate additions return an error. Deletions are irreversible — confirm secret names before submitting. related: tutorials: - title: Deploy your Node.js app href: /docs/api-users/hosting/workflows/deploy-nodejs-app guides: - title: Manage apps href: /docs/api-users/hosting/manage-apps concepts: - title: Hosting concepts href: /docs/api-users/hosting/concepts apis: - title: Secrets reference href: /docs/references/rest/hosting/list-secrets --- ## Overview This page covers managing environment secrets for a hosted app. You configure secrets per variant (`PREVIEW` or `PUBLISH`). A single call can add, update, or delete them. The API never returns secret values. Go to [Deploy your Node.js app](https://developer.godaddy.com/docs/api-users/hosting/workflows/deploy-nodejs-app) if you haven't created and deployed an app yet. Go to [Hosting concepts](https://developer.godaddy.com/docs/api-users/hosting/concepts) for background on the variant model. ## Prerequisites The following prerequisites are required before you can manage secrets for your app: * a [Personal Access Token](https://developer.godaddy.com/personal-access-token) with the `hosting.secret:read` scope (list operations) or `hosting.secret:write` scope (write operations) ## List secrets `GET /apps/{appId}/secrets` returns a deduplicated flat list of secret metadata for the app. Values are never included. The following procedure lists secrets for an app. * List secrets: ```bash tab="curl" curl -s "$BASE_URL/v1/hosting/apps/$APP_ID/secrets?variant=PREVIEW" \ -H "Authorization: Bearer $GODADDY_PAT" | jq . ``` ```js tab="Node" const res = await fetch( `${process.env.BASE_URL}/v1/hosting/apps/${appId}/secrets?variant=PREVIEW`, { headers: { Authorization: `Bearer ${process.env.GODADDY_PAT}` } }, ); const secrets = await res.json(); ``` ```python tab="Python" import requests, os resp = requests.get( f"{os.environ['BASE_URL']}/v1/hosting/apps/{app_id}/secrets?variant=PREVIEW", headers={"Authorization": f"Bearer {os.environ['GODADDY_PAT']}"}, ) secrets = resp.json() ``` ```go tab="Go" req, _ := http.NewRequest("GET", os.Getenv("BASE_URL")+"/v1/hosting/apps/"+appID+"/secrets?variant=PREVIEW", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT")) resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() ``` The response includes secret names and last-updated timestamps. Values are omitted. ## Add, update, or delete secrets `PATCH /apps/{appId}/secrets` applies a [JSON Patch (RFC 6902)](https://datatracker.ietf.org/doc/html/rfc6902) array atomically. Pass the environment as the `variant` query parameter (`PREVIEW` or `PUBLISH`). Each call accepts up to 50 operations total. Supported ops are `add`, `replace`, and `remove`. Each path is `/{name}`. The following procedure adds a new preview secret, updates an existing preview secret, and deletes another preview secret in one call. * Submit the patch: ```bash tab="curl" curl -s -X PATCH "$BASE_URL/v1/hosting/apps/$APP_ID/secrets?variant=PREVIEW" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "Content-Type: application/json-patch+json" \ -d '[ { "op": "add", "path": "/STRIPE_KEY", "value": "sk_test_abc123" }, { "op": "replace", "path": "/DB_URL", "value": "postgres://host/newdb" }, { "op": "remove", "path": "/OLD_FLAG" } ]' | jq . ``` ```js tab="Node" const res = await fetch(`${process.env.BASE_URL}/v1/hosting/apps/${appId}/secrets?variant=PREVIEW`, { method: 'PATCH', headers: { Authorization: `Bearer ${process.env.GODADDY_PAT}`, 'Content-Type': 'application/json-patch+json', }, body: JSON.stringify([ { op: 'add', path: '/STRIPE_KEY', value: 'sk_test_abc123' }, { op: 'replace', path: '/DB_URL', value: 'postgres://host/newdb' }, { op: 'remove', path: '/OLD_FLAG' }, ]), }); const result = await res.json(); ``` ```python tab="Python" import json, requests, os resp = requests.patch( f"{os.environ['BASE_URL']}/v1/hosting/apps/{app_id}/secrets?variant=PREVIEW", headers={ "Authorization": f"Bearer {os.environ['GODADDY_PAT']}", "Content-Type": "application/json-patch+json", }, data=json.dumps([ {"op": "add", "path": "/STRIPE_KEY", "value": "sk_test_abc123"}, {"op": "replace", "path": "/DB_URL", "value": "postgres://host/newdb"}, {"op": "remove", "path": "/OLD_FLAG"}, ]), ) ``` ```go tab="Go" body := `[ {"op": "add", "path": "/STRIPE_KEY", "value": "sk_test_abc123"}, {"op": "replace", "path": "/DB_URL", "value": "postgres://host/newdb"}, {"op": "remove", "path": "/OLD_FLAG"} ]` req, _ := http.NewRequest("PATCH", os.Getenv("BASE_URL")+"/v1/hosting/apps/"+appID+"/secrets?variant=PREVIEW", strings.NewReader(body)) req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT")) req.Header.Set("Content-Type", "application/json-patch+json") resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() ``` The response is secret metadata. Values are never included. ## Common errors The following table lists common errors and recommended actions: | Status | Cause | Action | | ------ | ---------------------------------------- | --------------------------------------------------------------------------------------------- | | `401` | Expired or revoked PAT, or missing scope | Confirm the token includes `hosting.secret:read` for list or `hosting.secret:write` for patch | | `404` | App id not found | Confirm the id from `GET /apps` | | `409` | Secret already exists (on `add`) | Use `replace` instead of `add` for existing secrets | | `422` | Validation error | Check the patch array structure, op values (`add`/`replace`/`remove`), and path format | | `429` | Rate limit exceeded | Back off and retry. Go to [Rate limits](https://developer.godaddy.com/docs/api-users/rate-limits) for handling guidance | # How to read logs (https://developer.godaddy.com/en/docs/api-users/hosting/read-logs) --- title: How to read logs description: >- Fetch application logs for a hosting app by environment, source stream, and time range. keywords: >- GET /apps/{appId}/logs, variant preview publish logs, source stdout stderr, since time range, level filter, hosting.log:read agentNotes: scopes: - 'hosting.log:read' idempotent: true destructive: false failureRecovery: >- Log reads are safe to retry. Empty response means no logs match the filters — adjust source, since, or variant. related: tutorials: - title: Deploy your Node.js app href: /docs/api-users/hosting/workflows/deploy-nodejs-app guides: - title: Troubleshoot Hosting href: /docs/api-users/troubleshoot/hosting concepts: - title: Hosting concepts href: /docs/api-users/hosting/concepts apis: - title: Logs reference href: /docs/references/rest/hosting/get-logs --- ## Overview This page covers fetching logs for a hosted app. The logs endpoint returns application output from both `PREVIEW` and `PUBLISH` environments and supports filtering by source stream (`STDOUT` or `STDERR`), severity level, and time range. By default, logs return the last 24 hours; you can request up to 7 days in the past. Go to [Deploy your Node.js app](https://developer.godaddy.com/docs/api-users/hosting/workflows/deploy-nodejs-app) if you haven't created and deployed an app yet. Go to [Troubleshoot Hosting](https://developer.godaddy.com/docs/api-users/troubleshoot/hosting) for guidance on diagnosing specific failures. For the complete list of query parameters and response schema, go to [Logs API reference](https://developer.godaddy.com/docs/references/rest/hosting/get-logs). ## Prerequisites The following prerequisites are required before you can read logs for your app: * a [Personal Access Token](https://developer.godaddy.com/personal-access-token) with the `hosting.log:read` scope ## Get logs The following procedure fetches all logs from the `PREVIEW` variant (default). * Fetch logs from `PREVIEW`: ```bash tab="curl" curl -s "$BASE_URL/v1/hosting/apps/$APP_ID/logs" \ -H "Authorization: Bearer $GODADDY_PAT" | jq . ``` ```js tab="Node" const res = await fetch( `${process.env.BASE_URL}/v1/hosting/apps/${appId}/logs`, { headers: { Authorization: `Bearer ${process.env.GODADDY_PAT}` } }, ); const logs = await res.json(); ``` ```python tab="Python" resp = requests.get( f"{os.environ['BASE_URL']}/v1/hosting/apps/{app_id}/logs", headers={"Authorization": f"Bearer {os.environ['GODADDY_PAT']}"}, ) logs = resp.json() ``` ```go tab="Go" req, _ := http.NewRequest("GET", os.Getenv("BASE_URL")+"/v1/hosting/apps/"+appID+"/logs", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT")) resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() ``` ## Read production logs The following procedure fetches all logs from the `PUBLISH` variant. Every app has two parallel variants: `PREVIEW` (working copy) and `PUBLISH` (live traffic). Go to [Hosting concepts](https://developer.godaddy.com/docs/api-users/hosting/concepts#variants) for more information. * Fetch production logs: ## Filter by severity level The following procedure fetches only error-level logs. * Fetch error logs: ```bash tab="curl" curl -s "$BASE_URL/v1/hosting/apps/$APP_ID/logs?level=ERROR" \ -H "Authorization: Bearer $GODADDY_PAT" | jq . ``` ```js tab="Node" const res = await fetch( `${process.env.BASE_URL}/v1/hosting/apps/${appId}/logs?level=ERROR`, { headers: { Authorization: `Bearer ${process.env.GODADDY_PAT}` } }, ); const logs = await res.json(); ``` ```python tab="Python" resp = requests.get( f"{os.environ['BASE_URL']}/v1/hosting/apps/{app_id}/logs", headers={"Authorization": f"Bearer {os.environ['GODADDY_PAT']}"}, params={"level": "ERROR"}, ) logs = resp.json() ``` ```go tab="Go" req, _ := http.NewRequest("GET", os.Getenv("BASE_URL")+"/v1/hosting/apps/"+appID+"/logs?level=ERROR", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT")) resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() ``` ## Filter by time range The following procedure fetches logs written at or after a specific timestamp. * Fetch logs since the timestamp: ```bash tab="curl" curl -s "$BASE_URL/v1/hosting/apps/$APP_ID/logs?since=2024-01-15T10:00:00Z" \ -H "Authorization: Bearer $GODADDY_PAT" | jq . ``` ```js tab="Node" const res = await fetch( `${process.env.BASE_URL}/v1/hosting/apps/${appId}/logs?since=2024-01-15T10:00:00Z`, { headers: { Authorization: `Bearer ${process.env.GODADDY_PAT}` } }, ); const logs = await res.json(); ``` ```python tab="Python" resp = requests.get( f"{os.environ['BASE_URL']}/v1/hosting/apps/{app_id}/logs", headers={"Authorization": f"Bearer {os.environ['GODADDY_PAT']}"}, params={"since": "2024-01-15T10:00:00Z"}, ) logs = resp.json() ``` ```go tab="Go" req, _ := http.NewRequest("GET", os.Getenv("BASE_URL")+"/v1/hosting/apps/"+appID+"/logs?since=2024-01-15T10:00:00Z", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT")) resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() ``` ## Common errors The following table lists common errors and recommended actions: | Status | Cause | Action | | ------ | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `401` | Expired or revoked PAT, or missing scope | Confirm the token includes `hosting.log:read` | | `404` | App id not found | Confirm the id from `GET /apps` | | `400` | Invalid parameter value | Use uppercase for `variant` (`PREVIEW` or `PUBLISH`), `source` (`STDOUT` or `STDERR`), and `level` (`INFO`, `WARN`, `ERROR`) | | `429` | Rate limit exceeded | Back off and retry. Go to [Rate limits](https://developer.godaddy.com/docs/api-users/rate-limits) for handling guidance | # 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. # Troubleshoot authentication (https://developer.godaddy.com/en/docs/api-users/troubleshoot/authentication) --- title: Troubleshoot authentication description: >- Common authentication errors when calling GoDaddy APIs, with causes and resolutions. keywords: >- 401 UNAUTHORIZED, 403 ACCOUNT_NOT_ELIGIBLE, 422 NO_PAYMENT_PROFILE, sso-key format, Bearer token expired revoked, scope mismatch 403, domains.domain:read required write, token stops working agentNotes: scopes: - Any — this page covers cross-cutting auth issues rateLimit: N/A (diagnostic reference) failureRecovery: >- Diagnostic page. On 401, check token format and expiration. On 403, distinguish scope vs eligibility via the code field. faqItems: - question: Why do I get 401 Unauthorized from the GoDaddy API? answer: >- The Authorization header is missing, malformed, or the token has expired or been revoked. Verify the format is 'Authorization: Bearer {token}', check the token hasn't expired, and confirm it hasn't been revoked on the Personal Access Token page. - question: Why do I get 403 Forbidden despite having a valid token? answer: >- The token doesn't include the scope required for the operation. Generate a new token with the required scopes. The domains.domain:read scope is required even for write operations that need to verify state. - question: Why do I get 403 ACCOUNT_NOT_ELIGIBLE? answer: >- The account doesn't meet eligibility requirements — typically a missing payment profile or domain ownership requirement. Add a payment method or verify you hold at least one domain. - question: Why do I get 422 NO_PAYMENT_PROFILE on purchase calls? answer: >- The operation requires a funded billing method (registration, renewal, transfer) but no payment method is on file. Add a payment method to your account. - question: Why did my token stop working after previously working? answer: >- The token has expired (PATs have configurable expiration) or was revoked. Check the expiration date, generate a new token if needed, and update your secrets manager. related: guides: - title: Authenticate href: /docs/api-users/auth - title: Set up a payment profile href: /docs/api-users/payment-profile - title: Troubleshoot your first call href: /docs/api-users/troubleshoot/first-call concepts: - title: Error handling href: /docs/api-users/errors --- ## Overview This page covers the most common authentication and authorization errors you'll encounter when calling GoDaddy APIs. Each section describes the symptom, cause, and resolution. ## 401 Unauthorized **Symptom:** API returns `401` with `code: "UNAUTHORIZED"`. **Cause:** The `Authorization` header is missing, malformed, or the token has expired or been revoked. **Resolution:** * Verify the header format is `Authorization: Bearer ` (no extra whitespace or quotes around the token value). * Check the token hasn't expired — PATs have a configurable expiration. Generate a new one if needed. * Confirm the token hasn't been revoked on the [Personal Access Token](https://developer.godaddy.com/personal-access-token) page. * If using `sso-key`, verify the format is `sso-key :` with no extra spaces. ## 403 Forbidden — missing scope **Symptom:** API returns `403` with a code indicating insufficient permissions, despite a valid token. **Cause:** The token is valid but doesn't include the scope required for the operation. **Resolution:** * Check the `code` field in the error response — it distinguishes between scope and eligibility issues. * Generate a new token with the required scopes. Go to [Authentication — PAT scopes](https://developer.godaddy.com/docs/api-users/auth#pat-scopes) for the full list. * The `domains.domain:read` scope is required even for write operations that need to verify state. ## 403 Forbidden — account eligibility **Symptom:** API returns `403` with a code like `ACCOUNT_NOT_ELIGIBLE` despite having the correct scope. **Cause:** The account doesn't meet the eligibility requirements for the operation — typically a missing payment profile or domain ownership requirement. **Resolution:** * For billing-related eligibility: add a payment method. Go to [Set up a payment profile](https://developer.godaddy.com/docs/api-users/payment-profile). * For domain management eligibility: the account must hold at least one domain or be on a plan that grants management access. * Check the `code` field — don't rely on HTTP status alone to distinguish scope from eligibility issues. ## 422 with `NO_PAYMENT_PROFILE` **Symptom:** API returns `422` with `code: "NO_PAYMENT_PROFILE"` on quote or purchase calls. **Cause:** The operation requires a funded billing method (registration, renewal, transfer) but the account has no payment method on file. **Resolution:** Add a payment method. Go to [Set up a payment profile](https://developer.godaddy.com/docs/api-users/payment-profile). ## Token stops working after working previously **Symptom:** A token that was working returns `401` without any code changes. **Cause:** The token expired (PATs have a configurable expiration) or was revoked. **Resolution:** * Check the token's expiration date on the [Personal Access Token](https://developer.godaddy.com/personal-access-token) page. * If expired or revoked, generate a new token. * Update your secrets manager or environment variable with the new value. # Troubleshoot the CLI (https://developer.godaddy.com/en/docs/api-users/troubleshoot/cli) --- title: Troubleshoot the CLI description: >- Common errors when installing or using the GoDaddy CLI (gddy), with causes and resolutions. keywords: >- command not found gddy, PATH ~/.local/bin, %LOCALAPPDATA% Programs gddy, OAuth redirect localhost, Gatekeeper macOS blocked binary, Set-ExecutionPolicy PowerShell, gddy auth status, install.sh permission denied agentNotes: scopes: - N/A — CLI handles auth internally rateLimit: N/A (diagnostic reference) failureRecovery: >- Diagnostic page. For PATH issues, open a new terminal. For auth issues, run 'gddy auth login'. For permission errors, check OS security settings. CLI targets one environment at a time — verify with 'gddy auth status'. faqItems: - question: 'Why does ''command not found: gddy'' appear after installation?' answer: >- Your PATH doesn't include the directory where the CLI was installed. In a terminal window, verify the binary exists at ~/.local/bin/gddy (or %LOCALAPPDATA%\Programs\gddy on Windows), and add the bin directory to PATH if needed. - question: Why does 'gddy auth login' open a browser but nothing happens? answer: >- The browser can't complete the OAuth redirect back to the CLI's local listener. Ensure you're not in a headless environment, try copying the URL manually, check for proxy interference with localhost, or try a different browser. - question: Why does 'gddy domain suggest' return an authentication error? answer: >- Authentication hasn't been configured or the saved token has expired. Run 'gddy auth status' to check, then 'gddy auth login' to re-authenticate if needed. - question: Why does the CLI installer fail with a permission error? answer: >- The script can't write to the target directory, or macOS Gatekeeper is blocking the binary. The installer defaults to ~/.local/bin (macOS/Linux) or %LOCALAPPDATA%\Programs\gddy (Windows), both user-writable, and falls back to sudo automatically on macOS/Linux only if that directory isn't writable. On macOS, allow in Security & Privacy settings if Gatekeeper blocks the binary. On Windows, no elevation should be needed unless you passed a system-owned --prefix. - question: Why do CLI commands return different results than curl? answer: >- The CLI might be using different credentials than your curl commands. Check with 'gddy auth status' and re-authenticate if needed. related: guides: - title: Set up the CLI href: /docs/api-users/cli/set-up - title: CLI reference href: /docs/api-users/cli/reference - title: Troubleshoot authentication href: /docs/api-users/troubleshoot/authentication - title: Make your first call href: /docs/api-users/quickstart --- ## Overview This page covers errors you may encounter when installing, authenticating, or using the `gddy` CLI. If you're setting up for the first time, go to [Set up the CLI](https://developer.godaddy.com/docs/api-users/cli/set-up) for the installation guide. If a command itself is throwing an error, check the [CLI reference](https://developer.godaddy.com/docs/api-users/cli/reference) to confirm you're using the right flags. ## `command not found: gddy` **Symptom:** Running `gddy` returns "command not found" or "not recognized" after installation. **Cause:** Your PATH does not include the directory where the CLI was installed. **Resolution:** * **Windows:** `install.ps1` adds the install directory to your user `PATH` automatically, but only new terminal sessions pick up the change — open a new terminal and try again. * **macOS/Linux:** `install.sh` does not modify your `PATH`. Add the bin directory manually, then add the same line to your shell profile (e.g. `~/.zshrc` or `~/.bashrc`) to persist it: ```bash export PATH="$HOME/.local/bin:$PATH" ``` * Verify the binary exists: `ls ~/.local/bin/gddy` (macOS/Linux) or check `%LOCALAPPDATA%\Programs\gddy\` (Windows). * Re-run the installer if the binary doesn't exist. ## `gddy auth login` opens a browser but nothing happens **Symptom:** The CLI opens a browser tab for OAuth login, but the redirect fails or hangs. **Cause:** The browser can't complete the OAuth redirect back to the CLI's local listener. **Resolution:** * Make sure you're not in a headless/SSH environment without browser access. * If the browser opened but the page failed to load, copy the URL from the terminal output and paste it manually. * If behind a corporate proxy, the redirect URL (`localhost`) may be intercepted — check with your network team. * Try a different browser if the default one has strict security extensions blocking localhost redirects. ## `gddy domain suggest` returns an authentication error **Symptom:** Running domain commands returns an auth-related error. **Cause:** Authentication hasn't been configured, or the saved token has expired. **Resolution:** * Run `gddy auth status` to check whether you're authenticated and which environment you're targeting. * If expired or not authenticated, run `gddy auth login` to re-authenticate. * If targeting the wrong environment, use `gddy auth login --env prod` (or `--env ote`) to specify. ## Installer fails with a permission error **Symptom:** The install script exits with "Permission denied" or similar. **Cause:** The script can't write to the target directory, or macOS Gatekeeper is blocking the binary. **Resolution:** * The installer defaults to `~/.local/bin` (macOS/Linux) or `%LOCALAPPDATA%\Programs\gddy` (Windows) — both are user-writable, so this shouldn't come up on a default install. * On macOS: if you see "cannot be opened because the developer cannot be verified," go to System Preferences → Security & Privacy → General and click "Allow Anyway." * On Linux: if you passed a `--prefix` pointing at a directory you don't own (e.g. `/usr/local/bin`), the installer falls back to `sudo` automatically. * On Windows PowerShell: if the execution policy blocks running the remote script via `iex`, run `Set-ExecutionPolicy -Scope Process Bypass` for the session, or download `install.ps1` and inspect it before running. ## CLI commands work but return different results than curl **Symptom:** The CLI returns different data or errors compared to the same operation via curl. **Cause:** The CLI might be using different credentials than your curl commands. **Resolution:** * Check your current environment: `gddy auth status` * If targeting the wrong environment, re-authenticate against the correct one. * Compare the base URL: CLI uses the environment from its auth config, while curl hits whatever URL you specify directly. # Troubleshoot DNS (https://developer.godaddy.com/en/docs/api-users/troubleshoot/dns) --- title: Troubleshoot DNS description: >- Common errors when managing DNS records with the GoDaddy Domains API, with causes and resolutions. keywords: >- DNS propagation TTL, dig @ns1.domaincontrol.com, domains.dns:update, domains.nameserver:update, CNAME apex 422, recordId Location header, PUT nameservers endpoint, NS SOA not modifiable, 429 Retry-After. agentNotes: scopes: - 'domains.domain:read' - 'domains.dns:update' - 'domains.nameserver:update' idempotent: false destructive: true failureRecovery: >- Read operations are safe to retry. DNS deletes are irreversible. Re-read the zone after failures to verify state. If nameservers were replaced incorrectly, issue a corrective PUT immediately. faqItems: - question: Why aren't my DNS changes showing up? answer: >- DNS propagation is not instantaneous. GoDaddy's authoritative nameservers apply changes within minutes, but external resolvers cache records for up to the previous TTL duration. Wait for the TTL to expire before assuming propagation has failed. Use a tool like dig @8.8.8.8 to bypass local cache. - question: Why do I get 400 when adding a DNS record? answer: >- The request body failed validation. Common causes: invalid record type, malformed data value (for example, an A record with a hostname instead of an IP address), unsupported name format, or a TTL below the minimum (600 seconds). Check the fields array in the error response for the specific field and reason. - question: Why do I get 403 Forbidden on a DNS request? answer: >- The token doesn't include the required scope. Read operations need domains.domain:read, write operations need domains.dns:update, and nameserver replacement needs domains.nameserver:update. Generate a new token with the correct scopes. - question: Why do I get 404 on a DNS record operation? answer: >- Either the recordId doesn't exist, the domain doesn't exist in your account, or the domain name in the zone path parameter is wrong. Save the recordId from the Location header when you create a record. Don't construct it manually. Verify the domain is visible via GET /v1/domains. - question: Why can't I delete NS or SOA records? answer: >- GoDaddy manages NS and SOA records as part of its hosted DNS infrastructure. These records cannot be deleted or overwritten through the DNS records API. To change nameservers, use the nameservers endpoint (PUT /v3/domains/zones/{domain}/nameservers) instead. - question: Why does adding a CNAME return 422? answer: >- You can't add a CNAME at the zone apex (@ or the root domain). Use A/AAAA records at the apex instead. For SRV records, the service and protocol fields must be underscore-prefixed (for example, _http and _tcp). - question: Why am I getting 429 rate limit errors? answer: >- The API enforces a per-credential, windowed rate limit. Check the Retry-After response header and wait that many seconds before retrying. For bulk operations, add a delay between requests or batch reads and writes. Go to /docs/api-users/rate-limits for current values. - question: Why does my DNS record add keep returning a duplicate record error? answer: >- The POST /v3/domains/zones/{domain}/dns-records endpoint appends records. If you already have a record with the same type, name, and data, the API may reject the duplicate depending on the record type. Read the current records first, then delete the existing one before adding the updated version. - question: How long does DNS propagation take after a record change? answer: >- GoDaddy's authoritative nameservers apply changes within minutes. External resolvers (Google, Cloudflare, ISPs) cache the old values for up to the previous TTL duration. If the old TTL was 3600 seconds (1 hour), expect up to 1 hour for global propagation. Lowering the TTL before a change speeds up subsequent propagation. related: guides: - title: Manage DNS records href: /docs/api-users/domains/manage/dns - title: Troubleshoot your first API call href: /docs/api-users/troubleshoot/first-call - title: Troubleshoot authentication href: /docs/api-users/troubleshoot/authentication apis: - title: 'Domains v3: DNS records' href: /docs/references/rest/domains/v3/list-dns-records concepts: - title: Error handling href: /docs/api-users/errors --- ## Overview This page covers errors you're likely to encounter when managing DNS records through the GoDaddy Domains API. For the full DNS management guide, go to [Manage DNS records](https://developer.godaddy.com/docs/api-users/domains/manage/dns). ## DNS changes not visible after update **Symptom:** You added or updated a DNS record and the change isn't reflected when you query the domain. **Cause:** DNS propagation is not instantaneous. Two distinct timelines apply: * **Authoritative nameservers** (GoDaddy): changes apply within minutes. * **External resolvers** (Google 8.8.8.8, Cloudflare 1.1.1.1, ISPs): resolvers cache the old value for up to the previous TTL duration. **Resolution:** * Query the authoritative nameserver directly to confirm the change was applied: `dig @ns1.domaincontrol.com your-domain.com A` * If the authoritative server shows the new value, the change is live: you're waiting for resolver caches to expire. * If the authoritative server still shows the old value, verify the API call succeeded by reading the record: `GET /v3/domains/zones/{domain}/dns-records` * To reduce future propagation time, lower the TTL to 600 seconds before making a planned change, then restore it afterward. ## `400` when adding a DNS record **Symptom:** `POST /v3/domains/zones/{domain}/dns-records` returns `400` with a `fields` array. **Cause:** The request body failed field-level validation. Common causes: * **Invalid `type`**: Only supported record types are accepted (`A`, `AAAA`, `CNAME`, `MX`, `NS`, `TXT`, `SRV`, `CAA`). * **Malformed `data`**: An `A` record must have an IPv4 address, not a hostname. A `CNAME` must be a fully qualified domain name ending with `.`. * **`ttl` below minimum**: The minimum TTL is 600 seconds. * **Invalid `name` format**: Use `@` for the apex record, not the domain name itself. **Resolution:** * Inspect each item in the `fields` array: `path` identifies the field, `message` describes the constraint. * Verify the `data` format against the record type. For example: `"data": "192.0.2.1"` for an `A` record, `"data": "mail.example.com."` for an `MX` record. * Set `ttl` to at least `600`. ## `NS` or `SOA` records can't be modified **Symptom:** Attempting to delete or replace `NS` or `SOA` records returns an error or has no effect. **Cause:** GoDaddy manages `NS` and `SOA` records as part of its hosted DNS infrastructure. These records cannot be deleted or overwritten through the DNS records endpoint. **Resolution:** * To change nameservers, use the dedicated nameservers endpoint: `PUT /v3/domains/zones/{domain}/nameservers` with an array of new nameserver hostnames. * `SOA` records are system-managed and cannot be changed directly. Changes to `NS` records propagate the `SOA` automatically. * If you need to delegate DNS to an external provider (Route 53, Cloudflare), replace the nameservers entirely using the nameservers endpoint, then manage all records there. ## Duplicate record error on `POST` **Symptom:** `POST /v3/domains/zones/{domain}/dns-records` returns an error indicating a conflicting or duplicate record already exists. **Cause:** The `POST` endpoint appends records. If a record with the same type, name, and data already exists, the API rejects the duplicate. Adding a record that violates DNS constraints (for example, a `CNAME` at the apex) also returns an error. **Resolution:** 1. Read the current zone: `GET /v3/domains/zones/{domain}/dns-records?type={TYPE}&name={NAME}` 2. Delete the conflicting record: `DELETE /v3/domains/zones/{domain}/dns-records/{recordId}` 3. Add the updated record: `POST /v3/domains/zones/{domain}/dns-records` To replace all records of a given type and name in one operation, use `PUT /v3/domains/zones/{domain}/dns-records/{type}/{name}`. ## `403 Forbidden`: insufficient scope **Symptom:** API returns `403` despite a valid token. **Cause:** The token doesn't include the scope required for the operation. **Resolution:** * Read operations require `domains.domain:read`. * Write operations (create, delete records) require `domains.dns:update`. * Nameserver replacement requires `domains.nameserver:update`. * Generate a new token with the correct scopes. Go to [Authenticate](https://developer.godaddy.com/docs/api-users/auth#pat-scopes) for the full scope list. ## `404 Not Found`: record or domain not found **Symptom:** API returns `404` on a read, delete, or nameserver operation. **Cause:** The `recordId` doesn't exist, the domain doesn't exist, or the domain isn't owned by the authenticated account. **Resolution:** * Verify the `zone` path parameter matches the domain name exactly (for example, `example.com`, not `www.example.com`). * For deletes: save the `recordId` from the `Location` header at create time. Don't construct `recordId` values manually. * Confirm the domain is visible via `GET /v1/domains`. If not found there, it isn't accessible with the current credential. ## `422 Unprocessable`: business rule violation **Symptom:** API returns `422` after accepting the request structure. **Cause:** The request is structurally valid but violates a DNS rule. The most common case is a `CNAME` at the zone apex. **Resolution:** * Do not create a `CNAME` record with `name: "@"` (the apex). Use `A`/`AAAA` records at the apex instead. * For `SRV` records, verify the `service` and `protocol` fields are underscore-prefixed (for example, `_http` and `_tcp`). ## `429 Too Many Requests`: rate limit exceeded **Symptom:** API returns `429`. **Cause:** The request rate exceeded the per-credential limit for the current window. **Resolution:** * Check the `Retry-After` response header and wait that many seconds before retrying. * For bulk operations, add a delay between requests or batch reads and writes. * Go to [Rate limits](https://developer.godaddy.com/docs/api-users/rate-limits) for the full rate limit reference. # Troubleshoot domain registration (https://developer.godaddy.com/en/docs/api-users/troubleshoot/domain-registration) --- title: Troubleshoot domain registration description: >- Common errors when registering a domain with the GoDaddy Domains API, with causes and resolutions. keywords: >- EXECUTING COMPLETED FAILED registrationId, QUOTE_EXPIRED quoteToken, Idempotency-Key duplicate charge, ACCOUNT_NOT_ELIGIBLE, punycode A-label IDN, contact field validation 422, GET /v3/domains/registrations, async registration polling. agentNotes: scopes: - 'domains.domain:read' - 'domains.domain:create' idempotent: false failureRecovery: >- Registration charges the account. Do not resubmit while status is EXECUTING. Use the Idempotency-Key header to prevent duplicate charges. If QUOTE_EXPIRED, re-quote and re-register. faqItems: - question: >- Why does domain registration return EXECUTING instead of completing immediately? answer: >- Registration is asynchronous. EXECUTING means the operation is in progress. Poll GET /v3/domains/registrations/{registrationId} until status is COMPLETED or FAILED. Do not resubmit. Use the Idempotency-Key header to prevent duplicate charges if your client retries. - question: Why does my registration return 422 QUOTE_EXPIRED? answer: >- The quoteToken from the registration-quotes endpoint has expired. Quote tokens are short-lived. Re-call POST /v3/domains/registration-quotes to get a fresh token, then submit the registration again with the new token. - question: Why is my registration returning 422 with a fields array? answer: >- The request body failed field-level validation. Common causes: missing or invalid registrant contact (email, phone, address), domain name format error, or TLD-specific requirements not met. Check each object in the fields array. The path and message identify which field failed and why. - question: Why does my registration return 422 NO_PAYMENT_PROFILE? answer: >- The account has no payment method on file. Registration charges the billing method. It cannot proceed without one. Add a payment method at https://account.godaddy.com/payment-methods or go to Set up a payment profile in the docs. - question: How do I prevent duplicate charges if my registration client retries? answer: >- Include an Idempotency-Key header with a stable, unique value (a UUID per registration attempt). If the server already processed a request with that key, it returns the original response without charging again. - question: Why is my registration returning 403 ACCOUNT_NOT_ELIGIBLE? answer: >- Write operations that cost money require a billing method on the account. Go to https://account.godaddy.com/payment-methods to add a payment method. The account might also be ineligible for specific TLD registrations. - question: >- Why did my domain registration return 422 saying the domain is not available? answer: >- The domain was registered by someone else between your availability check and the registration attempt, or it's in a status that prevents registration (for example, redemption period). Call GET /v3/domains/check-availability immediately before registering. Don't cache availability results. Use the suggestions endpoint to find alternatives if the domain is taken. related: guides: - title: Register a domain href: /docs/api-users/domains/register - title: Set up a payment profile href: /docs/api-users/payment-profile - title: Troubleshoot authentication href: /docs/api-users/troubleshoot/authentication apis: - title: v3 Registrations href: /docs/references/rest/domains/v3/register-domain - title: v3 Registration Quotes href: /docs/references/rest/domains/v3/quote-domain-registration concepts: - title: Error handling href: /docs/api-users/errors --- ## Overview This page covers errors you're likely to encounter when registering a domain through the GoDaddy Domains API. Registration is asynchronous and charges the account. Read the [full registration guide](https://developer.godaddy.com/docs/api-users/domains/register) before troubleshooting. ## Registration stays in `EXECUTING` status **Symptom:** `POST /v3/domains/registrations` returns `202 Accepted` and the status field shows `EXECUTING`. The status never changes to `COMPLETED`. **Cause:** Registration is asynchronous. `EXECUTING` is the normal initial state: the operation is in progress on GoDaddy's side. It is not an error. **Resolution:** * Poll `GET /v3/domains/registrations/{registrationId}` every few seconds until `status` reaches `COMPLETED` or `FAILED`. * Do not resubmit the registration while `status` is `EXECUTING`. Resubmitting can result in duplicate charges. * If `status` is `FAILED`, inspect the `error` field for the specific failure reason. * Use the `Idempotency-Key` header on the original request: if your client retries due to a network error, the server returns the original response without charging again. ## `422` with `QUOTE_EXPIRED` **Symptom:** `POST /v3/domains/registrations` returns `422` with `code: "QUOTE_EXPIRED"`. **Cause:** The `quoteToken` from `POST /v3/domains/registration-quotes` has expired. Quote tokens are short-lived and expire within a minute of issue. **Resolution:** 1. Call `POST /v3/domains/registration-quotes` again with the same domain and contact details to get a fresh `quoteToken`. 2. Resubmit `POST /v3/domains/registrations` with the new `quoteToken`. 3. If you're seeing this frequently, reduce the time between quoting and registering: keep it under a minute in production flows. ## `422` with a `fields` validation error **Symptom:** `POST /v3/domains/registrations` returns `422` with a `fields` array listing specific field errors. **Cause:** The request body failed field-level validation. Common causes: * Missing or invalid registrant contact: `email`, `phone`, `addressMailing`, or `nameFirst`/`nameLast` not provided or malformed. * Domain name format error: unsupported characters, missing TLD, or invalid punycode. * TLD-specific requirements not met: some TLDs require additional contact fields or eligibility verification. **Resolution:** * Inspect each object in the `fields` array: the `path` field identifies which request property failed and `message` explains why. * Verify all required registrant contact fields are present. Go to [Register a domain: contacts](https://developer.godaddy.com/docs/api-users/domains/register#registrant-contact) for the required schema. * For IDN (internationalized) domains, the domain name must be in punycode A-label form. ## `403` with `ACCOUNT_NOT_ELIGIBLE` **Symptom:** `POST /v3/domains/registrations` or `POST /v3/domains/registration-quotes` returns `403` with `code: "ACCOUNT_NOT_ELIGIBLE"`. **Cause:** The account lacks a funded billing method, or is not eligible to register the specific TLD. **Resolution:** * Add a payment method at [your account settings](https://account.godaddy.com/payment-methods). Go to [Set up a payment profile](https://developer.godaddy.com/docs/api-users/payment-profile). * Some TLDs (country-code TLDs, restricted TLDs) require additional account eligibility. Check the TLD-specific agreements returned by `GET /v3/domains/agreements?tlds={tld}`. ## Duplicate charge on retry **Symptom:** A network failure caused the client to retry the registration, and the account was charged twice. **Cause:** The first request succeeded server-side but the response was lost in transit. The retry created a second registration. **Resolution:** * Always include an `Idempotency-Key` header with a UUID that's stable for the lifetime of a single registration intent. * If a request returns a network error (not a `4xx` or `5xx`), retry with the same `Idempotency-Key`. The server returns the original response without charging again. * If a duplicate charge already occurred, contact GoDaddy support with the `registrationId` values. ## Domain not available **Symptom:** `POST /v3/domains/registrations` returns `422` with a code indicating the domain isn't available. **Cause:** Someone registered or reserved the domain between your availability check and the attempt, or the domain is in a restricted status (for example, redemption period). **Resolution:** * Call `GET /v3/domains/check-availability` immediately before registering. Don't cache availability results. * If the exact domain is unavailable, use the suggestions endpoint to find alternatives. * Go to [Search domain availability](https://developer.godaddy.com/docs/api-users/domains/search) for the availability check workflow. ## `422` with `NO_PAYMENT_PROFILE` **Symptom:** API returns `422` with `code: "NO_PAYMENT_PROFILE"`. **Cause:** The account has no payment method on file. Registration charges the billing method and cannot proceed without one. **Resolution:** * Add a payment method. Go to [Set up a payment profile](https://developer.godaddy.com/docs/api-users/payment-profile). * Once a payment method is on file, retry the registration with a fresh `quoteToken`. # Troubleshoot your first API call (https://developer.godaddy.com/en/docs/api-users/troubleshoot/first-call) --- title: Troubleshoot your first API call description: >- Common errors when making your first call to the GoDaddy Domains API, with causes and resolutions. keywords: >- Could not resolve host api.godaddy.com, echo GODADDY_PAT, HTTPS_PROXY curl proxy, curl --max-time timeout, definitive field optimizeFor ACCURACY, domains.domain:read 403, first API call 401, punycode domain encoding agentNotes: scopes: - 'domains.domain:read' failureRecovery: >- Diagnostic page. All operations mentioned are read-only and safe to retry. On 401, verify token. On 403, check scopes. On timeout, check network. faqItems: - question: Why does curl say 'Could not resolve host' for api.godaddy.com? answer: >- DNS can't resolve the API hostname. Verify internet connectivity, check corporate proxy settings (--proxy flag or HTTPS_PROXY), or disconnect VPN to rule out DNS filtering. - question: Why do I get 401 Unauthorized on my first API call? answer: >- The Authorization header is missing or the token value is wrong. Confirm your env var is set (echo $GODADDY_PAT), verify the format is 'Bearer {token}' with no extra quotes, and ensure you exported it in the same shell session. - question: Why does the availability check return 403 Forbidden? answer: >- Your token doesn't have the domains.domain:read scope. Generate a new PAT with at least the domains.domain:read scope. - question: Why is the JSON response empty or unexpected? answer: >- The domain parameter is likely malformed — missing the TLD, containing invalid characters, or using unsupported encoding. Use a fully-qualified domain name like 'your-idea.com' and ensure no invisible characters are present. - question: >- Why does the availability check say a domain is unavailable when it appears unregistered? answer: >- The domain may be reserved, premium, or in a registry hold state. Check the 'definitive' field — if false, retry with optimizeFor=ACCURACY for a live registry check. Some TLDs reserve common words. - question: Why is the API connection timing out? answer: >- Network issues, firewall blocking HTTPS to external hosts, or API degraded performance. Test connectivity with 'curl -I https://api.godaddy.com', ensure port 443 is open, and add --max-time 30 to your curl commands. related: guides: - title: Make your first call href: /docs/api-users/quickstart - title: Troubleshoot authentication href: /docs/api-users/troubleshoot/authentication - title: Search domain availability href: /docs/api-users/domains/search concepts: - title: Error handling href: /docs/api-users/errors - title: Rate limits href: /docs/api-users/rate-limits --- ## Overview This page covers errors you're likely to encounter during your first API calls. If you're getting started, go to the [quickstart](https://developer.godaddy.com/docs/api-users/quickstart) for the happy path first. ## `curl: (6) Could not resolve host` **Symptom:** curl reports it can't resolve `api.godaddy.com`. **Cause:** DNS can't resolve the API hostname. Typically a network or proxy issue. **Resolution:** * Verify internet connectivity (`curl https://google.com`). * If behind a corporate proxy, configure curl to use it with the `--proxy` flag or `HTTPS_PROXY` environment variable. * If on a VPN, try disconnecting temporarily to rule out DNS filtering. ## 401 Unauthorized on first call **Symptom:** Your first API call returns `401`. **Cause:** The `Authorization` header is missing or the token value is wrong. **Resolution:** * Confirm the environment variable is set: `echo $GODADDY_PAT` should print the token value. * Verify the header format is `Bearer ` — no extra quotes, no `"Bearer "` with a trailing space. * Make sure you exported the variable in the same shell session where you're running curl. * Go to [Troubleshoot authentication](https://developer.godaddy.com/docs/api-users/troubleshoot/authentication) for deeper auth issues. ## 403 Forbidden on availability check **Symptom:** `GET /v3/domains/check-availability` returns `403`. **Cause:** The token doesn't have the `domains.domain:read` scope. **Resolution:** Generate a new PAT with at least the `domains.domain:read` scope. Go to [Authentication — PAT scopes](https://developer.godaddy.com/docs/api-users/auth#pat-scopes). ## Empty or unexpected JSON response **Symptom:** The response is empty, missing fields, or returns an unexpected structure. **Cause:** The domain parameter is malformed — missing the TLD, contains invalid characters, or uses an unsupported encoding. **Resolution:** * Use a fully-qualified domain name including the TLD: `your-idea.com`, not `your-idea`. * IDN (internationalized) domains must use punycode A-label form. * Check for invisible characters copied from other sources (zero-width spaces, smart quotes). ## `available: false` for a domain you expected to be available **Symptom:** The availability check returns `false` for a domain that appears unregistered. **Cause:** The domain may be reserved, premium, or in a registry hold state that makes it unavailable through standard registration. **Resolution:** * The `definitive` field indicates whether the result came from a live registry check. If `false`, try again with `optimizeFor=ACCURACY` for a live check. * Some TLDs reserve common words or short names. Try alternative TLDs. * Premium domains may be available but at higher pricing — check the aftermarket. ## Connection timeout or slow responses **Symptom:** curl hangs or times out connecting to the API. **Cause:** Network issues, firewall blocking HTTPS to external hosts, or the API is experiencing degraded performance. **Resolution:** * Test basic connectivity: `curl -I https://api.godaddy.com` * Check your firewall allows outbound HTTPS (port 443) to `api.godaddy.com`. * Add a timeout to your curl commands: `curl --max-time 30 ...` # Troubleshoot Node.js Hosting (https://developer.godaddy.com/en/docs/api-users/troubleshoot/hosting) --- title: Troubleshoot Node.js Hosting description: >- Diagnose and resolve common errors when deploying and operating Node.js apps on GoDaddy's hosting platform. agentNotes: scopes: - 'hosting.application:read' - 'hosting.log:read' idempotent: true destructive: false failureRecovery: All diagnostic calls on this page are read-only and safe to retry. faqItems: - question: Why is my hosting app creation job stuck in pending? answer: >- Most create-app jobs complete within a minute. If the job stays in pending for more than 2 minutes, treat it as stuck — retry the POST /apps call with a new name. - question: Why did my zip upload fail? answer: >- The most common cause is a missing package.json at the zip root, a missing build or start script, or node_modules included in the zip. Verify the zip structure against the Node.js app requirements. - question: Why am I getting 401 Unauthorized from the Hosting API? answer: >- The token is expired, revoked, or missing a required scope. Verify the required scope is included in your PAT. Create a new PAT with the correct scopes. - question: Why is the publish variant not showing running after deployment? answer: >- Allow up to 30 seconds for the variant status to flip to running after POST /apps/{appId}/deployments. If it stays in a non-running state, fetch application logs to check for startup errors. keywords: >- job stuck pending, upload failed zip, 401 unauthorized hosting, 429 rate limit, deployment failed, hosting.secret:read scope, app not running, troubleshoot hosting related: tutorials: - title: Deploy your Node.js app href: /docs/api-users/hosting/workflows/deploy-nodejs-app guides: - title: Read logs href: /docs/api-users/hosting/read-logs concepts: - title: Hosting concepts href: /docs/api-users/hosting/concepts - title: Node.js app requirements href: /docs/api-users/hosting/app-requirements apis: - title: Hosting API reference href: /docs/references/rest/hosting --- ## Overview This page covers common failures when using the Hosting API, with causes and steps to resolve them. Go to [Read logs](https://developer.godaddy.com/docs/api-users/hosting/read-logs) for build and application output when diagnosing runtime failures. ## App creation job stuck in pending **Symptom:** `GET /app-operations/{operationId}` returns `status: "PENDING"` for more than two minutes. **Cause:** Upstream provisioning delay or a transient platform error. **Resolution:** * Wait two minutes. Most create jobs complete within 30–60 seconds. * If still pending after 2 minutes, treat the job as failed. * Retry `POST /apps` with a new app name. Don't reuse the stuck operation id. ## Source import job failed **Symptom:** `GET /apps/{appId}/imports/{importId}` returns `status: "FAILED"`. **Cause:** A malformed zip or build failure causes most import failures. **Resolution:** * Confirm the zip root contains a `package.json`. The build system must find it at the top level. * Confirm the zip doesn't contain a nested project root (e.g., a folder wrapping all the files). * Verify the app meets all deployment requirements. Go to [Node.js app requirements](https://developer.godaddy.com/docs/api-users/hosting/app-requirements) for the full list. * After fixing the zip, upload again with `POST /apps/{appId}/imports`. ## 401 Unauthorized **Symptom:** Any request returns `401 Unauthorized`. **Cause:** The token is expired, revoked, or missing a required scope. **Resolution:** 1. Check the token expiry date in the [Personal Access Tokens](https://developer.godaddy.com/personal-access-token) portal. 2. Verify the token includes the scope the operation requires. Go to [Hosting core concepts](https://developer.godaddy.com/docs/api-users/hosting/concepts#scopes-reference) for the full scopes table. 3. Note: `GET /apps/{appId}/secrets` requires `hosting.secret:read`. 4. Create a new token with the correct scopes if the original has expired or lacked a scope. ## 429 Too Many Requests **Symptom:** Requests return `429 Too Many Requests`. **Cause:** Rate limit exceeded. Limits are enforced per client IP and vary by operation (10–120 req/min). **Resolution:** * Implement exponential backoff. Start with a 1-second delay and double on each retry, up to a maximum of 30 seconds. * Avoid tight polling loops — use 2–5 second intervals when polling job status. * Go to [Rate limits](https://developer.godaddy.com/docs/api-users/rate-limits) for general guidance. ## App not running after publish **Symptom:** `GET /apps/{appId}/status` shows the `publish` variant in a non-running state after `POST /apps/{appId}/deployments`. **Cause:** The app might have a startup error, or the deployment is still rolling out. **Resolution:** 1. Allow up to 30 seconds for the status to flip to `running` after a publish. Poll with a five second interval. 2. If the status remains non-running, fetch application logs to check for startup errors. 3. Fix the error, upload a corrected zip, and publish again. Go to [Deploy your Node.js app](https://developer.godaddy.com/docs/api-users/hosting/workflows/deploy-nodejs-app) for the full deploy flow. 4. Fetch application logs: # Commerce API scopes (https://developer.godaddy.com/en/docs/references/rest/commerce-scopes) --- title: Commerce API scopes description: >- PAT scopes for the GoDaddy Commerce APIs, and the endpoints each scope unlocks. full: true --- Commerce APIs use PAT scopes to authorize requests. Scopes follow the pattern `commerce.:`. ## Permission values The `:` suffix on a scope maps to the HTTP methods it unlocks: | Permission | Use for | HTTP methods | | ---------- | -------------------------------------------------- | ------------------------- | | `read` | Read-only access | `GET` | | `write` | Create and update combined | `POST`, `PATCH`, `PUT` | | `create` | Create only (when separate from update) | `POST` | | `update` | Update only (when separate from create) | `PATCH`, `PUT` | | `delete` | Delete access | `DELETE` | | `execute` | Other operations (usually with an operation field) | varies | | `cancel` | Cancel a resource | `POST` (GraphQL mutation) | | `complete` | Complete a resource | `POST` (GraphQL mutation) | | `archive` | Archive a resource | `POST` (GraphQL mutation) | ## Store | Scope | Grants | Endpoints | | --------------------- | ---------------------- | -------------------------------------------------------------------------------------------- | | `commerce.store:read` | Read store information | `GET /v1/commerce/stores/{storeId}``GET /v1/commerce/stores/{storeId}/attributes/{attrName}` | ## Channel | Scope | Grants | Endpoints | | ----------------------- | ------------------- | ------------------------------------------------------------------ | | `commerce.channel:read` | Read sales channels | `GET /v1/commerce/channels``GET /v1/commerce/channels/{channelId}` | `GET /v1/commerce/channels/{channelId}` checks access on that specific channel. A PAT that can list channels for a store may still receive `401` on get-by-id. List channels and filter instead: ```bash curl -s "https://api.godaddy.com/v1/commerce/channels?registeredStores.storeId=${STORE_ID}" \ -H "Authorization: Bearer $GODADDY_PAT" \ | jq '.items[] | select(.channelId == "")' ``` ## Customer | Scope | Grants | Endpoints | | -------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------- | | `commerce.customer:read` | Read customers | `GET /v1/commerce/stores/{storeId}/customers``GET /v1/commerce/stores/{storeId}/customers/{customerId}` | | `commerce.customer:create` | Create customers | `POST /v1/commerce/stores/{storeId}/customers` | | `commerce.customer:update` | Update customer information | `PATCH /v1/commerce/stores/{storeId}/customers/{customerId}` | ## Product (Catalog GraphQL) | Scope | Grants | Endpoint | | ------------------------ | -------------------------- | ----------------------------------------------------- | | `commerce.product:read` | Read products | `POST /v2/commerce/stores/{storeId}/catalog-subgraph` | | `commerce.product:write` | Create and update products | `POST /v2/commerce/stores/{storeId}/catalog-subgraph` | ## Order (Order GraphQL) | Scope | Grants | Endpoint | | ------------------------- | --------------- | ---------------------------------- | | `commerce.order:read` | Read orders | `POST /v1/commerce/order-subgraph` | | `commerce.order:create` | Create orders | `POST /v1/commerce/order-subgraph` | | `commerce.order:update` | Update orders | `POST /v1/commerce/order-subgraph` | | `commerce.order:cancel` | Cancel orders | `POST /v1/commerce/order-subgraph` | | `commerce.order:complete` | Complete orders | `POST /v1/commerce/order-subgraph` | ## Tax (Tax GraphQL) | Scope | Grants | Endpoint | | --------------------- | ---------------------- | ------------------------------------------------- | | `commerce.tax:read` | Read taxes and rates | `POST /v2/commerce/stores/{storeId}/tax-subgraph` | | `commerce.tax:create` | Create taxes and rates | `POST /v2/commerce/stores/{storeId}/tax-subgraph` | | `commerce.tax:write` | Update taxes and rates | `POST /v2/commerce/stores/{storeId}/tax-subgraph` | | `commerce.tax:delete` | Delete taxes and rates | `POST /v2/commerce/stores/{storeId}/tax-subgraph` | ## Transaction | Scope | Grants | Endpoints | | --------------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------- | | `commerce.transaction:read` | Read transactions | `GET /v2/commerce/stores/{storeId}/transactions``GET /v2/commerce/stores/{storeId}/transactions/{transactionId}` | # REST API Reference (https://developer.godaddy.com/en/docs/references/rest) --- title: REST API Reference description: Complete REST API documentation with interactive examples full: true --- ## Domain Lifecycle ### Domains & DNS Manage domain registrations, DNS records, privacy settings, and transfers. Operations span version namespaces: **v1** is the original REST API; **v2** added async processing (action queues, notifications, and status polling) in 2019; **v3** is the newest API with a quote-execute registration model. Machine-readable OpenAPI specs: [domains-v1.json](https://developer.godaddy.com/openapi/domains-v1.json) and [domains-v2.json](https://developer.godaddy.com/openapi/domains-v2.json). *** ## Domain Marketplace & Aftermarket ### Aftermarket API Auction-related actions exclusive to allowlisted reseller partners (list, bid on, and manage aftermarket domain listings. Auth: sso-key). ### Auctions API Domain auction operations — retrieve active auctions, place bids, and manage auction state. Auth: sso-key. *** ## Domain Monetization ### Parking API Domain parking configuration — enable, disable, and manage monetized parked-page settings for domains. Auth: sso-key. *** ## Customer & Identity ### Agreements API Retrieve the legal agreements required for domain registration, transfers, and privacy changes. The `agreementKeys` returned here must be passed in the `consent` object when purchasing a domain. Auth: sso-key. ### Shoppers API Manage shopper accounts, subaccounts, and authentication used by resellers acting on behalf of customers. *** ## Security & Risk ### Abuse API Report and manage domain abuse cases. Auth: sso-key. ### Certificates API Manage SSL/TLS certificate orders, validation, reissuance, and domain verification. Auth: sso-key. *** ## Platform & Integration ### ANS API Agent Name Service (ANS) is a decentralized naming layer for registering, resolving, and managing ANS handles and identities. Auth: PAT. ### Hosting API Manage applications on GoDaddy hosting. Deploy, manage versions, configure environments, and view logs. *** ## Reference Data ### Countries API Country reference data — states and provinces, dialing codes, and country codes for use in contact and address fields. Auth: sso-key. # How to configure your taxes (https://developer.godaddy.com/en/docs/api-users/commerce/configure-taxes) --- title: How to configure your taxes description: >- Create and manage tax rates through the Tax GraphQL subgraph — the store-scoped endpoint for all tax configuration operations. keywords: >- taxRateId, createTaxRate, activateTaxRate, ACTIVE INACTIVE tax status, inclusive exclusive tax, tax jurisdiction, VAT GST, commerce.tax scope agentNotes: permissions: [] scopes: - 'commerce.tax:read' - 'commerce.tax:create' - 'commerce.tax:write' - 'commerce.tax:delete' idempotent: false destructive: false failureRecovery: >- Query operations are safe to retry. For mutations, check the current rate state with the rates query before retrying to avoid duplicate creates. related: apis: - title: Tax GraphQL reference href: /docs/references/rest/taxes 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 concepts: - title: About the Commerce API href: /docs/api-users/commerce - title: Authentication href: /docs/api-users/auth - title: Rate limits href: /docs/api-users/rate-limits - title: Paginate results href: /docs/api-users/pagination --- ## Overview Tax rates define what percentage is applied to purchases in your store. All Tax operations (reads, creates, status changes, and deletes) are GraphQL queries and mutations sent to `POST /v2/commerce/stores/{storeId}/tax-subgraph`. Send `x-store-id` on every request — that header is what the Tax subgraph authorizes against. If the header is missing, GraphQL returns `AUTHENTICATION_ERROR` (`Failed to authorize`) with HTTP 200. If the path `{storeId}` and header disagree, the header wins. The Tax subgraph also supports Classifications, Jurisdictions, and Overrides for more advanced tax configurations. This article covers the core rate operations. Go to the [Tax GraphQL reference](https://developer.godaddy.com/docs/references/rest/taxes) for the full schema. ## Prerequisites The following prerequisites are required before you can configure taxes: * a GoDaddy account with an active commerce store * a [Personal Access Token (PAT)](https://developer.godaddy.com/docs/api-users/auth) with the scopes for the operations you need (`commerce.tax:read` for queries; `commerce.tax:create`, `:write`, or `:delete` for the corresponding mutations) * your `storeId` Go to [Your stores](https://developer.godaddy.com/docs/api-users/commerce#your-stores) to find your store ID. ## List tax rates `rates(first, after, ...)` returns a paginated collection of rates. Results use edge-based cursor pagination. Go to [Paginate results](https://developer.godaddy.com/docs/api-users/pagination) for cursor-based pagination guidance. Optional `orderBy` takes **exactly one** of `id`, `name`, `createdAt`, or `updatedAt` with `ASC` or `DESC` — not `"desc"`, and not two keys in one object. The following procedure retrieves the first page of tax rates. 1. Query the first 10 tax rates: ```bash tab="curl" curl -s -X POST "https://api.godaddy.com/v2/commerce/stores/${STORE_ID}/tax-subgraph" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "x-store-id: ${STORE_ID}" \ -H "Content-Type: application/json" \ -d '{"query": "query GetRates($first: Int) { rates(first: $first) { edges { node { id name label status value { __typename ... on RatePercentage { percentage } ... on RateAmount { amount { value currencyCode } } } } } pageInfo { hasNextPage endCursor } } }", "variables": {"first": 10}}' ``` ```js tab="Node" const token = process.env.GODADDY_PAT; const storeId = process.env.STORE_ID; const res = await fetch( `https://api.godaddy.com/v2/commerce/stores/${storeId}/tax-subgraph`, { method: "POST", headers: { Authorization: `Bearer ${token}`, "x-store-id": storeId, "Content-Type": "application/json", }, body: JSON.stringify({ query: `query GetRates($first: Int) { rates(first: $first) { edges { node { id name label status value { __typename ... on RatePercentage { percentage } ... on RateAmount { amount { value currencyCode } } } } } pageInfo { hasNextPage endCursor } } }`, variables: { first: 10 }, }), } ); const data = await res.json(); console.log(data.data.rates); ``` ```python tab="Python" import os, requests token = os.environ["GODADDY_PAT"] store_id = os.environ["STORE_ID"] res = requests.post( f"https://api.godaddy.com/v2/commerce/stores/{store_id}/tax-subgraph", headers={ "Authorization": f"Bearer {token}", "x-store-id": store_id, "Content-Type": "application/json", }, json={ "query": "query GetRates($first: Int) { rates(first: $first) { edges { node { id name label status value { __typename ... on RatePercentage { percentage } ... on RateAmount { amount { value currencyCode } } } } } pageInfo { hasNextPage endCursor } } }", "variables": {"first": 10}, }, ) res.raise_for_status() print(res.json()["data"]["rates"]) ``` ```go tab="Go" package main import ( "bytes" "encoding/json" "fmt" "net/http" "os" ) func main() { token := os.Getenv("GODADDY_PAT") storeId := os.Getenv("STORE_ID") payload := map[string]any{ "query": `query GetRates($first: Int) { rates(first: $first) { edges { node { id name label status value { __typename ... on RatePercentage { percentage } ... on RateAmount { amount { value currencyCode } } } } } pageInfo { hasNextPage endCursor } } }`, "variables": map[string]any{"first": 10}, } body, _ := json.Marshal(payload) url := fmt.Sprintf("https://api.godaddy.com/v2/commerce/stores/%s/tax-subgraph", storeId) req, _ := http.NewRequest("POST", url, bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer "+token) req.Header.Set("x-store-id", storeId) req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() var result map[string]any json.NewDecoder(res.Body).Decode(&result) fmt.Println(result) } ``` 2. Review the paginated response: ```json { "data": { "rates": { "edges": [ { "node": { "id": "", "name": "", "label": "", "status": "", "value": { "__typename": "RatePercentage", "percentage": "" } } } ], "pageInfo": { "hasNextPage": false, "endCursor": "" } } } } ``` ## Get a tax rate `rate(id: ID!)` retrieves a single tax rate by its ID. The following procedure reads a single tax rate by ID. * Retrieve a tax rate by its `id`: ```bash tab="curl" RATE_ID="" curl -s -X POST "https://api.godaddy.com/v2/commerce/stores/${STORE_ID}/tax-subgraph" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "x-store-id: ${STORE_ID}" \ -H "Content-Type: application/json" \ -d "{\"query\": \"query GetRate(\$id: ID!) { rate(id: \$id) { id name label status value { __typename ... on RatePercentage { percentage } ... on RateAmount { amount { value currencyCode } } } createdAt } }\", \"variables\": {\"id\": \"${RATE_ID}\"}}" ``` ```js tab="Node" const token = process.env.GODADDY_PAT; const storeId = process.env.STORE_ID; const rateId = ""; const res = await fetch( `https://api.godaddy.com/v2/commerce/stores/${storeId}/tax-subgraph`, { method: "POST", headers: { Authorization: `Bearer ${token}`, "x-store-id": storeId, "Content-Type": "application/json", }, body: JSON.stringify({ query: `query GetRate($id: ID!) { rate(id: $id) { id name label status value { __typename ... on RatePercentage { percentage } ... on RateAmount { amount { value currencyCode } } } createdAt } }`, variables: { id: rateId }, }), } ); const data = await res.json(); console.log(data.data.rate); ``` ```python tab="Python" import os, requests token = os.environ["GODADDY_PAT"] store_id = os.environ["STORE_ID"] rate_id = "" res = requests.post( f"https://api.godaddy.com/v2/commerce/stores/{store_id}/tax-subgraph", headers={ "Authorization": f"Bearer {token}", "x-store-id": store_id, "Content-Type": "application/json", }, json={ "query": "query GetRate($id: ID!) { rate(id: $id) { id name label status value { __typename ... on RatePercentage { percentage } ... on RateAmount { amount { value currencyCode } } } createdAt } }", "variables": {"id": rate_id}, }, ) res.raise_for_status() print(res.json()["data"]["rate"]) ``` ```go tab="Go" package main import ( "bytes" "encoding/json" "fmt" "net/http" "os" ) func main() { token := os.Getenv("GODADDY_PAT") storeId := os.Getenv("STORE_ID") rateId := "" payload := map[string]any{ "query": `query GetRate($id: ID!) { rate(id: $id) { id name label status value { __typename ... on RatePercentage { percentage } ... on RateAmount { amount { value currencyCode } } } createdAt } }`, "variables": map[string]any{"id": rateId}, } body, _ := json.Marshal(payload) url := fmt.Sprintf("https://api.godaddy.com/v2/commerce/stores/%s/tax-subgraph", storeId) req, _ := http.NewRequest("POST", url, bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer "+token) req.Header.Set("x-store-id", storeId) req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() var result map[string]any json.NewDecoder(res.Body).Decode(&result) fmt.Println(result) } ``` ## Create a tax rate `createRate(input: MutationCreateRateInput!)` creates a new rate. `label` and `value` are required. `name` is generated from the label when omitted. `status` defaults to `ACTIVE`. `value` is a `RateValueInput`: set `percentage` (string, out of 100) or `amount` (`{ value, currencyCode }`), not both. For `amount.value`, send integer minor units (`850`, not `8.5`). Optional input fields from the schema: `calculationMethod` (`ADDITIVE` or `INCLUSIVE`; defaults to `ADDITIVE`), `description`, `jurisdictionId`, `metafields`, and `references`. You can omit `metafields` and `references` entirely. If you send `metafields`, the array must be nonempty — `[]` is rejected. Don't send `createdAt` or `updatedAt` — those fields exist only for Tax v1 to v2 migration. For metafields, prefer `type: "string"` (lowercase). When you **read** a rate, `value` is a union. Select it with inline fragments (`... on RatePercentage` / `... on RateAmount`) — there is no `value { rate }` field. The following procedure creates a new tax rate. 1. Create a tax rate with a label and value: ```bash tab="curl" curl -s -X POST "https://api.godaddy.com/v2/commerce/stores/${STORE_ID}/tax-subgraph" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "x-store-id: ${STORE_ID}" \ -H "Content-Type: application/json" \ -d '{ "query": "mutation CreateRate($input: MutationCreateRateInput!) { createRate(input: $input) { id name label status createdAt } }", "variables": { "input": { "label": "", "name": "", "value": { "percentage": "8.5" } } } }' ``` ```js tab="Node" const token = process.env.GODADDY_PAT; const storeId = process.env.STORE_ID; const res = await fetch( `https://api.godaddy.com/v2/commerce/stores/${storeId}/tax-subgraph`, { method: "POST", headers: { Authorization: `Bearer ${token}`, "x-store-id": storeId, "Content-Type": "application/json", }, body: JSON.stringify({ query: `mutation CreateRate($input: MutationCreateRateInput!) { createRate(input: $input) { id name label status createdAt } }`, variables: { input: { label: "", name: "", value: { percentage: "8.5" }, }, }, }), } ); const data = await res.json(); console.log(data.data.createRate); ``` ```python tab="Python" import os, requests token = os.environ["GODADDY_PAT"] store_id = os.environ["STORE_ID"] res = requests.post( f"https://api.godaddy.com/v2/commerce/stores/{store_id}/tax-subgraph", headers={ "Authorization": f"Bearer {token}", "x-store-id": store_id, "Content-Type": "application/json", }, json={ "query": "mutation CreateRate($input: MutationCreateRateInput!) { createRate(input: $input) { id name label status createdAt } }", "variables": { "input": { "label": "", "name": "", "value": {"percentage": "8.5"}, } }, }, ) res.raise_for_status() print(res.json()["data"]["createRate"]) ``` ```go tab="Go" package main import ( "bytes" "encoding/json" "fmt" "net/http" "os" ) func main() { token := os.Getenv("GODADDY_PAT") storeId := os.Getenv("STORE_ID") payload := map[string]any{ "query": `mutation CreateRate($input: MutationCreateRateInput!) { createRate(input: $input) { id name label status createdAt } }`, "variables": map[string]any{ "input": map[string]any{ "label": "", "name": "", "value": map[string]any{"percentage": "8.5"}, }, }, } body, _ := json.Marshal(payload) url := fmt.Sprintf("https://api.godaddy.com/v2/commerce/stores/%s/tax-subgraph", storeId) req, _ := http.NewRequest("POST", url, bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer "+token) req.Header.Set("x-store-id", storeId) req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() var result map[string]any json.NewDecoder(res.Body).Decode(&result) fmt.Println(result) } ``` 2. Save the `id` from the response (you'll need it to activate or modify the rate): ```json { "data": { "createRate": { "id": "", "name": "", "label": "", "status": "ACTIVE", "createdAt": "" } } } ``` ## Activate a tax rate `activateRate(id: ID!)` sets a rate's status to `ACTIVE`. Requires `commerce.tax:write`. The following procedure activates an existing tax rate. 1. Activate a rate by its `id`: ```bash tab="curl" RATE_ID="" curl -s -X POST "https://api.godaddy.com/v2/commerce/stores/${STORE_ID}/tax-subgraph" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "x-store-id: ${STORE_ID}" \ -H "Content-Type: application/json" \ -d "{\"query\": \"mutation ActivateRate(\$id: ID!) { activateRate(id: \$id) { id label status activatedAt } }\", \"variables\": {\"id\": \"${RATE_ID}\"}}" ``` ```js tab="Node" const token = process.env.GODADDY_PAT; const storeId = process.env.STORE_ID; const rateId = ""; const res = await fetch( `https://api.godaddy.com/v2/commerce/stores/${storeId}/tax-subgraph`, { method: "POST", headers: { Authorization: `Bearer ${token}`, "x-store-id": storeId, "Content-Type": "application/json", }, body: JSON.stringify({ query: `mutation ActivateRate($id: ID!) { activateRate(id: $id) { id label status activatedAt } }`, variables: { id: rateId }, }), } ); const data = await res.json(); console.log(data.data.activateRate); ``` ```python tab="Python" import os, requests token = os.environ["GODADDY_PAT"] store_id = os.environ["STORE_ID"] rate_id = "" res = requests.post( f"https://api.godaddy.com/v2/commerce/stores/{store_id}/tax-subgraph", headers={ "Authorization": f"Bearer {token}", "x-store-id": store_id, "Content-Type": "application/json", }, json={ "query": "mutation ActivateRate($id: ID!) { activateRate(id: $id) { id label status activatedAt } }", "variables": {"id": rate_id}, }, ) res.raise_for_status() print(res.json()["data"]["activateRate"]) ``` ```go tab="Go" package main import ( "bytes" "encoding/json" "fmt" "net/http" "os" ) func main() { token := os.Getenv("GODADDY_PAT") storeId := os.Getenv("STORE_ID") rateId := "" payload := map[string]any{ "query": `mutation ActivateRate($id: ID!) { activateRate(id: $id) { id label status activatedAt } }`, "variables": map[string]any{"id": rateId}, } body, _ := json.Marshal(payload) url := fmt.Sprintf("https://api.godaddy.com/v2/commerce/stores/%s/tax-subgraph", storeId) req, _ := http.NewRequest("POST", url, bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer "+token) req.Header.Set("x-store-id", storeId) req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() var result map[string]any json.NewDecoder(res.Body).Decode(&result) fmt.Println(result) } ``` 2. Confirm the rate status updated to `ACTIVE`: ```json { "data": { "activateRate": { "id": "", "label": "", "status": "ACTIVE", "activatedAt": "" } } } ``` ## Deactivate a tax rate `deactivateRate(id: ID!)` sets a rate's status to `INACTIVE`. Requires `commerce.tax:write`. Deactivated rates no longer apply to purchases. The following procedure deactivates an active tax rate. 1. Deactivate a rate by its `id`: ```bash tab="curl" RATE_ID="" curl -s -X POST "https://api.godaddy.com/v2/commerce/stores/${STORE_ID}/tax-subgraph" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "x-store-id: ${STORE_ID}" \ -H "Content-Type: application/json" \ -d "{\"query\": \"mutation DeactivateRate(\$id: ID!) { deactivateRate(id: \$id) { id label status } }\", \"variables\": {\"id\": \"${RATE_ID}\"}}" ``` ```js tab="Node" const token = process.env.GODADDY_PAT; const storeId = process.env.STORE_ID; const rateId = ""; const res = await fetch( `https://api.godaddy.com/v2/commerce/stores/${storeId}/tax-subgraph`, { method: "POST", headers: { Authorization: `Bearer ${token}`, "x-store-id": storeId, "Content-Type": "application/json", }, body: JSON.stringify({ query: `mutation DeactivateRate($id: ID!) { deactivateRate(id: $id) { id label status } }`, variables: { id: rateId }, }), } ); const data = await res.json(); console.log(data.data.deactivateRate); ``` ```python tab="Python" import os, requests token = os.environ["GODADDY_PAT"] store_id = os.environ["STORE_ID"] rate_id = "" res = requests.post( f"https://api.godaddy.com/v2/commerce/stores/{store_id}/tax-subgraph", headers={ "Authorization": f"Bearer {token}", "x-store-id": store_id, "Content-Type": "application/json", }, json={ "query": "mutation DeactivateRate($id: ID!) { deactivateRate(id: $id) { id label status } }", "variables": {"id": rate_id}, }, ) res.raise_for_status() print(res.json()["data"]["deactivateRate"]) ``` ```go tab="Go" package main import ( "bytes" "encoding/json" "fmt" "net/http" "os" ) func main() { token := os.Getenv("GODADDY_PAT") storeId := os.Getenv("STORE_ID") rateId := "" payload := map[string]any{ "query": `mutation DeactivateRate($id: ID!) { deactivateRate(id: $id) { id label status } }`, "variables": map[string]any{"id": rateId}, } body, _ := json.Marshal(payload) url := fmt.Sprintf("https://api.godaddy.com/v2/commerce/stores/%s/tax-subgraph", storeId) req, _ := http.NewRequest("POST", url, bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer "+token) req.Header.Set("x-store-id", storeId) req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() var result map[string]any json.NewDecoder(res.Body).Decode(&result) fmt.Println(result) } ``` 2. Confirm the rate status updated to `INACTIVE`: ```json { "data": { "deactivateRate": { "id": "", "label": "", "status": "INACTIVE" } } } ``` ## Delete a tax rate `deleteRate(id: ID!)` permanently removes a tax rate. Requires `commerce.tax:delete`. This action can't be undone. Use `deactivateRate` instead if you might need the rate again. The following procedure deletes a tax rate. 1. Delete a rate by its `id`: ```bash tab="curl" RATE_ID="" curl -s -X POST "https://api.godaddy.com/v2/commerce/stores/${STORE_ID}/tax-subgraph" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "x-store-id: ${STORE_ID}" \ -H "Content-Type: application/json" \ -d "{\"query\": \"mutation DeleteRate(\$id: ID!) { deleteRate(id: \$id) { id label } }\", \"variables\": {\"id\": \"${RATE_ID}\"}}" ``` ```js tab="Node" const token = process.env.GODADDY_PAT; const storeId = process.env.STORE_ID; const rateId = ""; const res = await fetch( `https://api.godaddy.com/v2/commerce/stores/${storeId}/tax-subgraph`, { method: "POST", headers: { Authorization: `Bearer ${token}`, "x-store-id": storeId, "Content-Type": "application/json", }, body: JSON.stringify({ query: `mutation DeleteRate($id: ID!) { deleteRate(id: $id) { id label } }`, variables: { id: rateId }, }), } ); const data = await res.json(); console.log(data); ``` ```python tab="Python" import os, requests token = os.environ["GODADDY_PAT"] store_id = os.environ["STORE_ID"] rate_id = "" res = requests.post( f"https://api.godaddy.com/v2/commerce/stores/{store_id}/tax-subgraph", headers={ "Authorization": f"Bearer {token}", "x-store-id": store_id, "Content-Type": "application/json", }, json={ "query": "mutation DeleteRate($id: ID!) { deleteRate(id: $id) { id label } }", "variables": {"id": rate_id}, }, ) res.raise_for_status() print(res.json()) ``` ```go tab="Go" package main import ( "bytes" "encoding/json" "fmt" "net/http" "os" ) func main() { token := os.Getenv("GODADDY_PAT") storeId := os.Getenv("STORE_ID") rateId := "" payload := map[string]any{ "query": `mutation DeleteRate($id: ID!) { deleteRate(id: $id) { id label } }`, "variables": map[string]any{"id": rateId}, } body, _ := json.Marshal(payload) url := fmt.Sprintf("https://api.godaddy.com/v2/commerce/stores/%s/tax-subgraph", storeId) req, _ := http.NewRequest("POST", url, bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer "+token) req.Header.Set("x-store-id", storeId) req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() var result map[string]any json.NewDecoder(res.Body).Decode(&result) fmt.Println(result) } ``` 2. `deleteRate` returns the deleted `Rate` object. Selecting no subfields is a GraphQL validation error (`Field "deleteRate" of type "Rate" must have a selection of subfields`). ```json { "data": { "deleteRate": { "id": "", "label": "" } } } ``` ## Common errors | Status | Most likely cause | Note | | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- | | `200` with `errors[].extensions.code: AUTHENTICATION_ERROR` | `x-store-id` is missing or is not a store this token can access. | Authorization uses the header, not the path `{storeId}`. | | `400` | GraphQL selection or variables are invalid. | `deleteRate` must select fields on `Rate`. `Rate.value` is a union — use `... on RatePercentage` / `... on RateAmount`. | | `401` | PAT is missing or expired. Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) to generate a new token. | | | `403` | Token doesn't include the required scope for the operation. | | | `404` | Tax rate ID doesn't exist or isn't accessible with the provided token. | | | `429` | Rate limit exceeded. | Honor the `Retry-After` header before retrying. | # How to manage catalog items (https://developer.godaddy.com/en/docs/api-users/commerce/manage-catalog) --- title: How to manage catalog items description: >- Create and manage SKUs and SKU groups through the Catalog GraphQL subgraph — the store-scoped endpoint for catalog operations. keywords: >- SKU ID, skuGroupId, createSKU, createSKUGroup, product variant, product listing, commerce.product scope, catalog GraphQL, inventory management agentNotes: permissions: [] scopes: - 'commerce.product:read' - 'commerce.product:write' rateLimit: >- Read RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset on each catalog-subgraph response. On 429, wait RateLimit-Reset or Retry-After. idempotent: false destructive: false failureRecovery: >- Query operations are safe to retry. For mutations, check the current state before retrying to avoid duplicate creates. related: apis: - title: Catalog GraphQL reference href: /docs/references/rest/catalog guides: - title: Manage a store href: /docs/api-users/commerce/set-up-a-store - title: Process an order href: /docs/api-users/commerce/manage-orders-and-customers - title: About the Commerce API href: /docs/api-users/commerce concepts: - title: Authentication href: /docs/api-users/auth - title: Rate limits href: /docs/api-users/rate-limits - title: Paginate results href: /docs/api-users/pagination --- ## Overview The Catalog subgraph manages SKUs and SKU groups (there's no `Product` type). A SKU is a single purchasable variant. A SKU group is a collection of related SKUs (for example, a shirt available in multiple sizes). All catalog operations go through one GraphQL endpoint: `POST /v2/commerce/stores/{storeId}/catalog-subgraph`. Send the same store ID in the `{storeId}` path and the `x-store-id` header. The header is required. If they differ, the subgraph uses the header — the path does not override it. Examples use `https://api.godaddy.com`. Use a [Personal Access Token](https://developer.godaddy.com/docs/api-users/auth) issued for the API host you call. Catalog scopes use `commerce.product:*` naming for historical reasons. Request `commerce.product:read` to query data and `commerce.product:write` for mutations. Read `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` on every catalog-subgraph response. On HTTP `429`, wait for `RateLimit-Reset` or `Retry-After`. See [Handle rate limits](https://developer.godaddy.com/docs/api-users/rate-limits). The following article describes how to manage catalog items. Go to [Catalog GraphQL reference](https://developer.godaddy.com/docs/references/rest/catalog) for more information about the Catalog subgraph. ## Prerequisites The following prerequisites are required before you can manage catalog items: * a GoDaddy account with an active commerce store * a [Personal Access Token (PAT)](https://developer.godaddy.com/docs/api-users/auth) with `commerce.product:read` (queries) or `commerce.product:write` (mutations) * your `storeId` 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`. ## List SKU groups `skuGroups` returns a paginated list of SKU groups for your store. Use `first` and `after` to page through results. The following procedure retrieves the first page of SKU groups. 1. Query SKU groups for your store: ```bash tab="curl" curl -s -X POST "https://api.godaddy.com/v2/commerce/stores/${STORE_ID}/catalog-subgraph" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "x-store-id: ${STORE_ID}" \ -H "Content-Type: application/json" \ -d '{"query": "{ skuGroups(first: 10) { edges { node { id label type status } } pageInfo { hasNextPage endCursor } } }"}' ``` ```js tab="Node" const token = process.env.GODADDY_PAT; const storeId = process.env.STORE_ID; const res = await fetch( `https://api.godaddy.com/v2/commerce/stores/${storeId}/catalog-subgraph`, { method: "POST", headers: { Authorization: `Bearer ${token}`, "x-store-id": storeId, "Content-Type": "application/json", }, body: JSON.stringify({ query: `{ skuGroups(first: 10) { edges { node { id label type status } } pageInfo { hasNextPage endCursor } } }`, }), } ); const { data } = await res.json(); console.log(data.skuGroups.edges.map((edge) => edge.node)); ``` ```python tab="Python" import os, requests token = os.environ["GODADDY_PAT"] store_id = os.environ["STORE_ID"] res = requests.post( f"https://api.godaddy.com/v2/commerce/stores/{store_id}/catalog-subgraph", headers={ "Authorization": f"Bearer {token}", "x-store-id": store_id, "Content-Type": "application/json", }, json={"query": "{ skuGroups(first: 10) { edges { node { id label type status } } pageInfo { hasNextPage endCursor } } }"}, ) res.raise_for_status() print([edge["node"] for edge in res.json()["data"]["skuGroups"]["edges"]]) ``` ```go tab="Go" package main import ( "bytes" "encoding/json" "fmt" "net/http" "os" ) func main() { token := os.Getenv("GODADDY_PAT") storeId := os.Getenv("STORE_ID") payload := map[string]any{ "query": "{ skuGroups(first: 10) { edges { node { id label type status } } pageInfo { hasNextPage endCursor } } }", } body, _ := json.Marshal(payload) url := fmt.Sprintf("https://api.godaddy.com/v2/commerce/stores/%s/catalog-subgraph", storeId) req, _ := http.NewRequest("POST", url, bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer "+token) req.Header.Set("x-store-id", storeId) req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() var result map[string]any json.NewDecoder(res.Body).Decode(&result) fmt.Println(result) } ``` 2. Review the response including SKU group IDs and the pagination cursor: ```json { "data": { "skuGroups": { "edges": [ { "node": { "id": "", "label": "", "type": "", "status": "" } } ], "pageInfo": { "hasNextPage": true, "endCursor": "" } } } } ``` To fetch the next page, pass the `endCursor` value as the `after` argument: `skuGroups(first: 10, after: "")`. ## Get a SKU group `skuGroup(id)` retrieves a single SKU group and its associated SKUs. * Retrieve a SKU group by its `id`: ```bash tab="curl" SKU_GROUP_ID="" curl -s -X POST "https://api.godaddy.com/v2/commerce/stores/${STORE_ID}/catalog-subgraph" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "x-store-id: ${STORE_ID}" \ -H "Content-Type: application/json" \ -d '{ "query": "query GetSkuGroup($id: String!) { skuGroup(id: $id) { id label type status skus { edges { node { id label code status } } } } }", "variables": { "id": "" } }' ``` ```js tab="Node" const token = process.env.GODADDY_PAT; const storeId = process.env.STORE_ID; const skuGroupId = ""; const res = await fetch( `https://api.godaddy.com/v2/commerce/stores/${storeId}/catalog-subgraph`, { method: "POST", headers: { Authorization: `Bearer ${token}`, "x-store-id": storeId, "Content-Type": "application/json", }, body: JSON.stringify({ query: `query GetSkuGroup($id: String!) { skuGroup(id: $id) { id label type status skus { edges { node { id label code status } } } } }`, variables: { id: skuGroupId }, }), } ); const { data } = await res.json(); console.log(data.skuGroup); ``` ```python tab="Python" import os, requests token = os.environ["GODADDY_PAT"] store_id = os.environ["STORE_ID"] sku_group_id = "" res = requests.post( f"https://api.godaddy.com/v2/commerce/stores/{store_id}/catalog-subgraph", headers={ "Authorization": f"Bearer {token}", "x-store-id": store_id, "Content-Type": "application/json", }, json={ "query": "query GetSkuGroup($id: String!) { skuGroup(id: $id) { id label type status skus { edges { node { id label code status } } } } }", "variables": {"id": sku_group_id}, }, ) res.raise_for_status() print(res.json()["data"]["skuGroup"]) ``` ```go tab="Go" package main import ( "bytes" "encoding/json" "fmt" "net/http" "os" ) func main() { token := os.Getenv("GODADDY_PAT") storeId := os.Getenv("STORE_ID") skuGroupId := "" payload := map[string]any{ "query": "query GetSkuGroup($id: String!) { skuGroup(id: $id) { id label type status skus { edges { node { id label code status } } } } }", "variables": map[string]any{"id": skuGroupId}, } body, _ := json.Marshal(payload) url := fmt.Sprintf("https://api.godaddy.com/v2/commerce/stores/%s/catalog-subgraph", storeId) req, _ := http.NewRequest("POST", url, bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer "+token) req.Header.Set("x-store-id", storeId) req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() var result map[string]any json.NewDecoder(res.Body).Decode(&result) fmt.Println(result) } ``` ## Create a SKU group `createSkuGroup` creates a new SKU group. The `label` and `type` fields are required. Live accepts `PHYSICAL`, `DIGITAL`, and `PRODUCT` for `type`. Metafield `type` must be lowercase (`string`, not `STRING`). The following procedure creates a SKU group. 1. Send the create mutation: ```bash tab="curl" curl -s -X POST "https://api.godaddy.com/v2/commerce/stores/${STORE_ID}/catalog-subgraph" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "x-store-id: ${STORE_ID}" \ -H "Content-Type: application/json" \ -d '{ "query": "mutation CreateSkuGroup($input: MutationCreateSkuGroupInput!) { createSkuGroup(input: $input) { id label type status } }", "variables": { "input": { "label": "", "type": "STANDARD" } } }' ``` ```js tab="Node" const token = process.env.GODADDY_PAT; const storeId = process.env.STORE_ID; const res = await fetch( `https://api.godaddy.com/v2/commerce/stores/${storeId}/catalog-subgraph`, { method: "POST", headers: { Authorization: `Bearer ${token}`, "x-store-id": storeId, "Content-Type": "application/json", }, body: JSON.stringify({ query: `mutation CreateSkuGroup($input: MutationCreateSkuGroupInput!) { createSkuGroup(input: $input) { id label type status } }`, variables: { input: { label: "", type: "STANDARD", }, }, }), } ); const { data } = await res.json(); console.log(data.createSkuGroup); ``` ```python tab="Python" import os, requests token = os.environ["GODADDY_PAT"] store_id = os.environ["STORE_ID"] res = requests.post( f"https://api.godaddy.com/v2/commerce/stores/{store_id}/catalog-subgraph", headers={ "Authorization": f"Bearer {token}", "x-store-id": store_id, "Content-Type": "application/json", }, json={ "query": "mutation CreateSkuGroup($input: MutationCreateSkuGroupInput!) { createSkuGroup(input: $input) { id label type status } }", "variables": {"input": {"label": "", "type": "STANDARD"}}, }, ) res.raise_for_status() print(res.json()["data"]["createSkuGroup"]) ``` ```go tab="Go" package main import ( "bytes" "encoding/json" "fmt" "net/http" "os" ) func main() { token := os.Getenv("GODADDY_PAT") storeId := os.Getenv("STORE_ID") payload := map[string]any{ "query": "mutation CreateSkuGroup($input: MutationCreateSkuGroupInput!) { createSkuGroup(input: $input) { id label type status } }", "variables": map[string]any{ "input": map[string]any{ "label": "", "type": "STANDARD", }, }, } body, _ := json.Marshal(payload) url := fmt.Sprintf("https://api.godaddy.com/v2/commerce/stores/%s/catalog-subgraph", storeId) req, _ := http.NewRequest("POST", url, bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer "+token) req.Header.Set("x-store-id", storeId) req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() var result map[string]any json.NewDecoder(res.Body).Decode(&result) fmt.Println(result) } ``` 2. Review the response including the new SKU group ID: ```json { "data": { "createSkuGroup": { "id": "", "label": "", "type": "STANDARD", "status": "" } } } ``` ## Create a SKU `createSku` creates a new SKU. The `label` field is required. Pass `skuGroupId` to attach it to a product (SKU group) in the same call, or use `addSkusToSkuGroup` afterwards. You can also create SKUs inline on `createSkuGroup` via `skus`. When you set `prices` or `unitCost`, for `SimpleMoneyInput.value` send `1999` for $19.99 USD, not `19.99`. Metafield `type` must be lowercase (`string`, not `STRING`). `createSku.label` is the variant label. The Commerce products UI uses the **SKU group** `label` as the product title. Changing a SKU label does not rename the product — use `updateSkuGroup` for that. To change an existing SKU price, use `updateSkuPrice`; `createSkuPrice` fails if the SKU already has a price. The following procedure creates a SKU. 1. Send the create mutation: ```bash tab="curl" curl -s -X POST "https://api.godaddy.com/v2/commerce/stores/${STORE_ID}/catalog-subgraph" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "x-store-id: ${STORE_ID}" \ -H "Content-Type: application/json" \ -d '{ "query": "mutation CreateSku($input: CreateSKUInput!) { createSku(input: $input) { id label code status } }", "variables": { "input": { "label": "", "code": "" } } }' ``` ```js tab="Node" const token = process.env.GODADDY_PAT; const storeId = process.env.STORE_ID; const res = await fetch( `https://api.godaddy.com/v2/commerce/stores/${storeId}/catalog-subgraph`, { method: "POST", headers: { Authorization: `Bearer ${token}`, "x-store-id": storeId, "Content-Type": "application/json", }, body: JSON.stringify({ query: `mutation CreateSku($input: CreateSKUInput!) { createSku(input: $input) { id label code status } }`, variables: { input: { label: "", code: "", }, }, }), } ); const { data } = await res.json(); console.log(data.createSku); ``` ```python tab="Python" import os, requests token = os.environ["GODADDY_PAT"] store_id = os.environ["STORE_ID"] res = requests.post( f"https://api.godaddy.com/v2/commerce/stores/{store_id}/catalog-subgraph", headers={ "Authorization": f"Bearer {token}", "x-store-id": store_id, "Content-Type": "application/json", }, json={ "query": "mutation CreateSku($input: CreateSKUInput!) { createSku(input: $input) { id label code status } }", "variables": {"input": {"label": "", "code": ""}}, }, ) res.raise_for_status() print(res.json()["data"]["createSku"]) ``` ```go tab="Go" package main import ( "bytes" "encoding/json" "fmt" "net/http" "os" ) func main() { token := os.Getenv("GODADDY_PAT") storeId := os.Getenv("STORE_ID") payload := map[string]any{ "query": "mutation CreateSku($input: CreateSKUInput!) { createSku(input: $input) { id label code status } }", "variables": map[string]any{ "input": map[string]any{ "label": "", "code": "", }, }, } body, _ := json.Marshal(payload) url := fmt.Sprintf("https://api.godaddy.com/v2/commerce/stores/%s/catalog-subgraph", storeId) req, _ := http.NewRequest("POST", url, bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer "+token) req.Header.Set("x-store-id", storeId) req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() var result map[string]any json.NewDecoder(res.Body).Decode(&result) fmt.Println(result) } ``` 2. Review the response including the new SKU ID: ```json { "data": { "createSku": { "id": "", "label": "", "code": "", "status": "" } } } ``` ## Update a SKU `updateSku` updates one or more fields on an existing SKU. All input fields are optional. Only include the fields you want to change. The following procedure updates the label of a SKU. 1. Send the update mutation: ```bash tab="curl" curl -s -X POST "https://api.godaddy.com/v2/commerce/stores/${STORE_ID}/catalog-subgraph" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "x-store-id: ${STORE_ID}" \ -H "Content-Type: application/json" \ -d '{ "query": "mutation UpdateSku($id: String!, $input: MutationUpdateSkuInput!) { updateSku(id: $id, input: $input) { id label code status } }", "variables": { "id": "", "input": { "label": "" } } }' ``` ```js tab="Node" const token = process.env.GODADDY_PAT; const storeId = process.env.STORE_ID; const res = await fetch( `https://api.godaddy.com/v2/commerce/stores/${storeId}/catalog-subgraph`, { method: "POST", headers: { Authorization: `Bearer ${token}`, "x-store-id": storeId, "Content-Type": "application/json", }, body: JSON.stringify({ query: `mutation UpdateSku($id: String!, $input: MutationUpdateSkuInput!) { updateSku(id: $id, input: $input) { id label code status } }`, variables: { id: "", input: { label: "", }, }, }), } ); const { data } = await res.json(); console.log(data.updateSku); ``` ```python tab="Python" import os, requests token = os.environ["GODADDY_PAT"] store_id = os.environ["STORE_ID"] res = requests.post( f"https://api.godaddy.com/v2/commerce/stores/{store_id}/catalog-subgraph", headers={ "Authorization": f"Bearer {token}", "x-store-id": store_id, "Content-Type": "application/json", }, json={ "query": "mutation UpdateSku($id: String!, $input: MutationUpdateSkuInput!) { updateSku(id: $id, input: $input) { id label code status } }", "variables": {"id": "", "input": {"label": ""}}, }, ) res.raise_for_status() print(res.json()["data"]["updateSku"]) ``` ```go tab="Go" package main import ( "bytes" "encoding/json" "fmt" "net/http" "os" ) func main() { token := os.Getenv("GODADDY_PAT") storeId := os.Getenv("STORE_ID") payload := map[string]any{ "query": "mutation UpdateSku($id: String!, $input: MutationUpdateSkuInput!) { updateSku(id: $id, input: $input) { id label code status } }", "variables": map[string]any{ "id": "", "input": map[string]any{"label": ""}, }, } body, _ := json.Marshal(payload) url := fmt.Sprintf("https://api.godaddy.com/v2/commerce/stores/%s/catalog-subgraph", storeId) req, _ := http.NewRequest("POST", url, bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer "+token) req.Header.Set("x-store-id", storeId) req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() var result map[string]any json.NewDecoder(res.Body).Decode(&result) fmt.Println(result) } ``` 2. Review the response confirming the updated fields: ```json { "data": { "updateSku": { "id": "", "label": "", "code": "", "status": "" } } } ``` ## Archive a SKU `archiveSku` marks a SKU as archived (there's no delete mutation). Archived SKUs are excluded from active queries unless you filter by `status: ARCHIVED`. * Archive a SKU by its `id`: ```bash tab="curl" curl -s -X POST "https://api.godaddy.com/v2/commerce/stores/${STORE_ID}/catalog-subgraph" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "x-store-id: ${STORE_ID}" \ -H "Content-Type: application/json" \ -d '{ "query": "mutation ArchiveSku($id: String!) { archiveSku(id: $id) { id status } }", "variables": { "id": "" } }' ``` ```js tab="Node" const token = process.env.GODADDY_PAT; const storeId = process.env.STORE_ID; const res = await fetch( `https://api.godaddy.com/v2/commerce/stores/${storeId}/catalog-subgraph`, { method: "POST", headers: { Authorization: `Bearer ${token}`, "x-store-id": storeId, "Content-Type": "application/json", }, body: JSON.stringify({ query: `mutation ArchiveSku($id: String!) { archiveSku(id: $id) { id status } }`, variables: { id: "" }, }), } ); const { data } = await res.json(); console.log(data.archiveSku); ``` ```python tab="Python" import os, requests token = os.environ["GODADDY_PAT"] store_id = os.environ["STORE_ID"] res = requests.post( f"https://api.godaddy.com/v2/commerce/stores/{store_id}/catalog-subgraph", headers={ "Authorization": f"Bearer {token}", "x-store-id": store_id, "Content-Type": "application/json", }, json={ "query": "mutation ArchiveSku($id: String!) { archiveSku(id: $id) { id status } }", "variables": {"id": ""}, }, ) res.raise_for_status() print(res.json()["data"]["archiveSku"]) ``` ```go tab="Go" package main import ( "bytes" "encoding/json" "fmt" "net/http" "os" ) func main() { token := os.Getenv("GODADDY_PAT") storeId := os.Getenv("STORE_ID") payload := map[string]any{ "query": "mutation ArchiveSku($id: String!) { archiveSku(id: $id) { id status } }", "variables": map[string]any{"id": ""}, } body, _ := json.Marshal(payload) url := fmt.Sprintf("https://api.godaddy.com/v2/commerce/stores/%s/catalog-subgraph", storeId) req, _ := http.NewRequest("POST", url, bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer "+token) req.Header.Set("x-store-id", storeId) req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() var result map[string]any json.NewDecoder(res.Body).Decode(&result) fmt.Println(result) } ``` ## Common errors | Status | Most likely cause | | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `400` | `x-store-id` header is missing, or the GraphQL selection is invalid (for example selecting `id` on the `Option` union without `... on ListOption`). A path `{storeId}` that doesn't match the header is not a 400 — the subgraph still uses `x-store-id`. | | `401` | PAT is missing or expired. Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) to generate a new token. | | `403` | Token doesn't include `commerce.product:read` or `commerce.product:write`. | | `404` | SKU or SKU group ID doesn't exist or isn't accessible with the provided token. | | `429` | Rate limit exceeded (`RateLimit-Remaining: 0`). Wait `RateLimit-Reset` seconds, or `Retry-After` if present. Do not assume 60 req/min. | GraphQL requests may return HTTP `200` even when there are errors. Always check the `errors` array in the response body. Schema validation errors (unknown fields, missing variables) return HTTP `400`, but runtime errors (invalid UUIDs, business rule violations) return HTTP `200` with an `errors` array alongside `data`. ## GraphQL behavior notes ### Non-existent IDs return null When you query an entity by ID (for example `skuGroup(id: "...")` or `sku(id: "...")`), a non-existent or inaccessible ID returns `null` with no error. This is standard GraphQL behavior, not a failure. ```json { "data": { "skuGroup": null } } ``` Code examples in the API reference use placeholder UUIDs like `ID_VALUE` or `497f6eca-6276-4993-bfeb-53cbbbba6f08`. These are documentation placeholders — replace them with real IDs from your store. Querying a placeholder UUID returns `null`. ### References are read via parent objects There is no top-level `reference(id: ...)` query. References follow a HATEOAS pattern — you read them through the parent object they're attached to: ```graphql # Read references on a SKU group query { skuGroup(id: "your-sku-group-id") { references { edges { node { id type value } } } } } ``` To manage references, use mutations like `addReferencesToSkuGroup`, `removeReferencesFromSkuGroup`, `addReferencesToSku`, etc. # How to manage a customer (https://developer.godaddy.com/en/docs/api-users/commerce/manage-orders-and-customers/customer) --- title: How to manage a customer description: 'Create, read, update customer profiles within a store.' keywords: >- customerId, createCustomer, updateCustomer, customer profile, email field, phone field, commerce.customer scope, customer record agentNotes: permissions: [] scopes: - 'commerce.customer:read' - 'commerce.customer:create' - 'commerce.customer:update' idempotent: false destructive: false failureRecovery: >- GET operations are safe to retry. For POST and PATCH, verify the current customer state before retrying to avoid duplicate creates or conflicting updates. related: apis: - title: Customer API reference href: /docs/references/rest/customers/fetch-customer guides: - title: Manage a store href: /docs/api-users/commerce/set-up-a-store - title: Process an order href: /docs/api-users/commerce/manage-orders-and-customers concepts: - title: About the Commerce API href: /docs/api-users/commerce - title: Authentication href: /docs/api-users/auth - title: Rate limits href: /docs/api-users/rate-limits --- ## Overview Customers are profiles associated with one or more orders in a store. The Customer API is a REST API. All operations use standard HTTP methods against store-scoped endpoints under `v1`. The following article provides examples of how to use the Customer API to manage customers in your store. ## Prerequisites The following prerequisites are required before you can manage customers: * a GoDaddy account with an active commerce store * a [Personal Access Token (PAT)](https://developer.godaddy.com/docs/api-users/auth) with the scopes for the operations you need (`commerce.customer:read` for reads; `commerce.customer:create` or `:update` for writes) * your `storeId` Go to [Your stores](https://developer.godaddy.com/docs/api-users/commerce#your-stores) to find your store ID. ## List customers `GET /v1/commerce/stores/{storeId}/customers` retrieves all customers for a store. Deleted customers are excluded by default. The following procedure lists customers in your store. 1. Retrieve a list of customers: ```bash tab="curl" curl -s "https://api.godaddy.com/v1/commerce/stores/${STORE_ID}/customers" \ -H "Authorization: Bearer $GODADDY_PAT" ``` ```js tab="Node" const token = process.env.GODADDY_PAT; const storeId = process.env.STORE_ID; const res = await fetch( `https://api.godaddy.com/v1/commerce/stores/${storeId}/customers`, { headers: { Authorization: `Bearer ${token}` } } ); const customers = await res.json(); console.log(customers); ``` ```python tab="Python" import os, requests token = os.environ["GODADDY_PAT"] store_id = os.environ["STORE_ID"] res = requests.get( f"https://api.godaddy.com/v1/commerce/stores/{store_id}/customers", headers={"Authorization": f"Bearer {token}"}, ) res.raise_for_status() print(res.json()) ``` ```go tab="Go" package main import ( "encoding/json" "fmt" "net/http" "os" ) func main() { token := os.Getenv("GODADDY_PAT") storeId := os.Getenv("STORE_ID") url := fmt.Sprintf("https://api.godaddy.com/v1/commerce/stores/%s/customers", storeId) req, _ := http.NewRequest("GET", url, nil) req.Header.Set("Authorization", "Bearer "+token) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() // The response is an object: { customers: [...], links: [...] }. var response map[string]any json.NewDecoder(res.Body).Decode(&response) fmt.Println(response["customers"]) } ``` 2. Review the response: ```json { "customers": [ { "customerId": "", "firstName": "", "lastName": "", "emails": [{ "email": "", "default": true }], "phones": [{ "phone": "", "default": true }], "createdAt": "", "updatedAt": "" } ], "links": [ { "rel": "self", "href": "https://api.godaddy.com/v1/commerce/stores//customers?page=1", "method": "GET" } ] } ``` Each customer is identified by `customerId`. Contact details (`emails`, `phones`) are arrays, not scalar fields — access them as `customer.emails[0].email`, not `customer.email`. The `links` array contains HATEOAS pagination cursors. Pass `totalRequired=true` to include `totalItems` and `totalPages` in the response. The returned `links` echo the current request (e.g. the `self` link above reflects the page you fetched). To page forward, prefer the `pageToken` from the previous response over incrementing the `page` param. ## Create a customer `POST /v1/commerce/stores/{storeId}/customers` creates a new customer or de-duplicates an existing one using channel data. If the supplied channel data matches an existing customer, the existing record is updated rather than a new one created. The request body has two top-level fields: a required `source` (the application creating the customer, e.g. `COMMERCE`) and a nested `customer` object holding the profile. Creation is **asynchronous** — a successful call returns `202 Accepted` with a `links` array rather than the created record. Send emails and phones as the `emails` and `phones` arrays, each with an `email` / `phone` sub-field. A top-level scalar `email` or `phone` is accepted with a `202` but **silently discarded** — the customer is created with no contact info. Always confirm with a follow-up GET. The following procedure creates a customer profile. 1. Create a customer with their contact details: ```bash tab="curl" curl -s -X POST "https://api.godaddy.com/v1/commerce/stores/${STORE_ID}/customers" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "Content-Type: application/json" \ -d '{ "source": "COMMERCE", "customer": { "firstName": "", "lastName": "", "emails": [{ "email": "", "default": true }], "phones": [{ "phone": "", "default": true }] } }' ``` ```js tab="Node" const token = process.env.GODADDY_PAT; const storeId = process.env.STORE_ID; const res = await fetch( `https://api.godaddy.com/v1/commerce/stores/${storeId}/customers`, { method: "POST", headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", }, body: JSON.stringify({ source: "COMMERCE", customer: { firstName: "", lastName: "", emails: [{ email: "", default: true }], phones: [{ phone: "", default: true }], }, }), } ); // 202 Accepted: parse the customerId out of the rel:"customer" link. const { links } = await res.json(); const customerHref = links.find((l) => l.rel === "customer")?.href; const customerId = customerHref?.split("/").pop(); console.log(customerId); ``` ```python tab="Python" import os, requests token = os.environ["GODADDY_PAT"] store_id = os.environ["STORE_ID"] res = requests.post( f"https://api.godaddy.com/v1/commerce/stores/{store_id}/customers", headers={ "Authorization": f"Bearer {token}", "Content-Type": "application/json", }, json={ "source": "COMMERCE", "customer": { "firstName": "", "lastName": "", "emails": [{"email": "", "default": True}], "phones": [{"phone": "", "default": True}], }, }, ) res.raise_for_status() # 202 Accepted print(res.json()["links"]) ``` ```go tab="Go" package main import ( "bytes" "encoding/json" "fmt" "net/http" "os" ) func main() { token := os.Getenv("GODADDY_PAT") storeId := os.Getenv("STORE_ID") payload := map[string]any{ "source": "COMMERCE", "customer": map[string]any{ "firstName": "", "lastName": "", "emails": []map[string]any{{"email": "", "default": true}}, "phones": []map[string]any{{"phone": "", "default": true}}, }, } body, _ := json.Marshal(payload) url := fmt.Sprintf("https://api.godaddy.com/v1/commerce/stores/%s/customers", storeId) req, _ := http.NewRequest("POST", url, bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer "+token) req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() var result map[string]any json.NewDecoder(res.Body).Decode(&result) fmt.Println(result["links"]) // 202 Accepted } ``` 2. The call returns `202 Accepted` with a `links` array — not the customer record. Read the `customerId` from the `href` of the link whose `rel` is `"customer"`: ```json { "links": [ { "rel": "customer", "href": "https://api.godaddy.com/v1/commerce/stores//customers/", "method": "GET" }, { "rel": "request", "href": "https://api.godaddy.com/v1/commerce/stores//customer-requests/", "method": "GET" } ] } ``` The `customerId` is the last path segment of the `rel: "customer"` href. GET that href to confirm the customer (and its contact details) persisted. The `rel: "request"` link tracks the async action and might not be accessible to PAT callers. ## Get a customer `GET /v1/commerce/stores/{storeId}/customers/{customerId}` retrieves a single customer by ID. The following procedure reads a single customer by ID. 1. Retrieve a single customer by its `customerId`: ```bash tab="curl" CUSTOMER_ID="" curl -s "https://api.godaddy.com/v1/commerce/stores/${STORE_ID}/customers/${CUSTOMER_ID}" \ -H "Authorization: Bearer $GODADDY_PAT" ``` ```js tab="Node" const token = process.env.GODADDY_PAT; const storeId = process.env.STORE_ID; const customerId = ""; const res = await fetch( `https://api.godaddy.com/v1/commerce/stores/${storeId}/customers/${customerId}`, { headers: { Authorization: `Bearer ${token}` } } ); const customer = await res.json(); console.log(customer); ``` ```python tab="Python" import os, requests token = os.environ["GODADDY_PAT"] store_id = os.environ["STORE_ID"] customer_id = "" res = requests.get( f"https://api.godaddy.com/v1/commerce/stores/{store_id}/customers/{customer_id}", headers={"Authorization": f"Bearer {token}"}, ) res.raise_for_status() print(res.json()) ``` ```go tab="Go" package main import ( "encoding/json" "fmt" "net/http" "os" ) func main() { token := os.Getenv("GODADDY_PAT") storeId := os.Getenv("STORE_ID") customerId := "" url := fmt.Sprintf("https://api.godaddy.com/v1/commerce/stores/%s/customers/%s", storeId, customerId) req, _ := http.NewRequest("GET", url, nil) req.Header.Set("Authorization", "Bearer "+token) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() var customer map[string]any json.NewDecoder(res.Body).Decode(&customer) fmt.Println(customer) } ``` 2. Review the response. The customer is returned wrapped in a `customer` object, alongside `links`. Use this GET to confirm that the `emails`/`phones` arrays and the latest `updatedAt` persisted after a create or update: ```json { "customer": { "customerId": "", "firstName": "", "lastName": "", "emails": [{ "email": "", "default": true }], "phones": [{ "phone": "", "default": true }], "createdAt": "", "updatedAt": "" }, "links": [] } ``` ## Update a customer `PATCH /v1/commerce/stores/{storeId}/customers/{customerId}` updates a customer. The body is a nested `customer` object containing the fields you want to change plus the current `updatedAt` value for optimistic concurrency. Like create, the update is **asynchronous** and returns `202 Accepted`. Include the `updatedAt` you received from your most recent GET. If it is missing the API returns `422`; if it is **stale** the API returns `202` but silently drops the update. After patching, re-GET the customer to confirm the change landed, and retry with the fresh `updatedAt` if it did not. The following procedure updates the email address for a customer. 1. GET the customer first (go to [Get a customer](#get-a-customer)) and note its current `updatedAt`. 2. Send the update as a nested `customer` object: ```bash tab="curl" CUSTOMER_ID="" curl -s -X PATCH "https://api.godaddy.com/v1/commerce/stores/${STORE_ID}/customers/${CUSTOMER_ID}" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "Content-Type: application/json" \ -d '{ "customer": { "emails": [{ "email": "", "default": true }], "updatedAt": "" } }' ``` ```js tab="Node" const token = process.env.GODADDY_PAT; const storeId = process.env.STORE_ID; const customerId = ""; const res = await fetch( `https://api.godaddy.com/v1/commerce/stores/${storeId}/customers/${customerId}`, { method: "PATCH", headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", }, body: JSON.stringify({ customer: { emails: [{ email: "", default: true }], updatedAt: "", }, }), } ); console.log(res.status); // 202 Accepted ``` ```python tab="Python" import os, requests token = os.environ["GODADDY_PAT"] store_id = os.environ["STORE_ID"] customer_id = "" res = requests.patch( f"https://api.godaddy.com/v1/commerce/stores/{store_id}/customers/{customer_id}", headers={ "Authorization": f"Bearer {token}", "Content-Type": "application/json", }, json={ "customer": { "emails": [{"email": "", "default": True}], "updatedAt": "", } }, ) res.raise_for_status() # 202 Accepted ``` ```go tab="Go" package main import ( "bytes" "encoding/json" "fmt" "net/http" "os" ) func main() { token := os.Getenv("GODADDY_PAT") storeId := os.Getenv("STORE_ID") customerId := "" payload := map[string]any{ "customer": map[string]any{ "emails": []map[string]any{{"email": "", "default": true}}, "updatedAt": "", }, } body, _ := json.Marshal(payload) url := fmt.Sprintf("https://api.godaddy.com/v1/commerce/stores/%s/customers/%s", storeId, customerId) req, _ := http.NewRequest("PATCH", url, bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer "+token) req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() fmt.Println(res.Status) // 202 Accepted } ``` ## Common errors | Status | Most likely cause | Note | | ------ | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | `400` | Malformed JSON in the request body. | | | `401` | PAT is missing or expired. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) to generate a new token. | | `403` | Token doesn't include the required scope (`commerce.customer:read`, `:create`, or `:update`). | | | `404` | Store ID or customer ID doesn't exist or isn't accessible with the provided token. | | | `422` | Body failed schema validation — e.g. a missing `updatedAt` on update, or a wrong contact sub-field name. | Response is a `ValidationError` with a `fields` array pinpointing each bad path. | | `429` | Rate limit exceeded. | Honor the `Retry-After` header before retrying. | ## Associate a customer with an order There is no dedicated "associate customer" endpoint. You link a customer to an order by setting both `customerId` and `billing` on the order via the Order subgraph GraphQL API (`addDraftOrder` or `updateOrder` mutations). ### What is billing The `billing` field is a nested object on the order that holds the buyer's contact information. It is not a separate API — you set it as part of the `addDraftOrder` or `updateOrder` mutation input. The fields are: | Field | Type | Required | Description | | ------------- | ------ | -------- | ------------------- | | `firstName` | String | Yes | Buyer first name | | `lastName` | String | Yes | Buyer last name | | `email` | String | Yes | Buyer email address | | `phone` | String | No | Buyer phone number | | `companyName` | String | No | Company name | | `address` | Object | No | Billing address | The `billing` object drives the customer-service integration. When an order with `billing` transitions to `OPEN`, the system uses that data to increment the customer's `orderCount` and establish the order–customer relationship internally. Setting only `customerId` creates a reference on the order but does not trigger the customer-service integration. The `billing` object (with at least `firstName`, `lastName`, and `email`) is what drives `orderCount` updates. Always provide both fields together. ### Behavior by combination | What you provide | `customerId` on order | `orderCount` increments | | ------------------------ | --------------------- | --------------------------- | | `customerId` only | Set | No | | `customerId` + `billing` | Set | Yes | | `billing` only | Not set | Yes (customer auto-created) | When you provide only `customerId`, the order stores the reference but the customer service does not learn about the order. The customer's `orderCount` stays at 0. When you provide both `customerId` and `billing`, the customer's `orderCount` increments when the order transitions to `OPEN`. When you provide only `billing`, the system auto-creates a customer record from the billing info with `orderCount` set to 1. However, the order's `customerId` field is not backfilled — the auto-created customer's `orderCount` reflects the relationship, but querying the order returns `customerId: null`. There is no way to discover the link from the order side. ### Recommended flow The following procedure creates a customer and associates it with a new order. 1. Create the customer via REST ([see above](#create-a-customer)) and note the `customerId`. 2. Create a draft order with both `customerId` and `billing`: ```bash tab="curl" curl -s "https://api.godaddy.com/v1/commerce/order-subgraph" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "x-store-id: $STORE_ID" \ -H "Content-Type: application/json" \ -d '{ "query": "mutation($input: AddDraftOrderInput!) { addDraftOrder(input: $input) { id customerId billing { firstName lastName email } } }", "variables": { "input": { "context": { "storeId": "", "channelId": "" }, "customerId": "", "billing": { "firstName": "", "lastName": "", "email": "", "phone": "" } } } }' ``` 3. Add line items with the `addLineItemBySkuId` mutation, then transition the order with `openOrder`. The customer's `orderCount` increments when the order reaches `OPEN`. To attach a customer to an existing order that has not yet been opened, use `updateOrder` with the same two fields while the order is still in `DRAFT`. The `orderCount` increment only fires during the `DRAFT` → `OPEN` transition — adding billing to an already-open order does not retroactively trigger it. ```bash tab="curl" curl -s "https://api.godaddy.com/v1/commerce/order-subgraph" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "x-store-id: $STORE_ID" \ -H "Content-Type: application/json" \ -d '{ "query": "mutation($input: UpdateOrderInput!) { updateOrder(input: $input) { id customerId billing { firstName lastName email } } }", "variables": { "input": { "id": "", "customerId": "", "billing": { "firstName": "", "lastName": "", "email": "", "phone": "" }, "context": { "storeId": "", "channelId": "" } } } }' ``` | Field | Where to find it | | --------------- | ------------------------------------------------------------ | | `ORDER_ID` | From `addDraftOrder` or `orders` query (e.g. `Order_abc123`) | | `CUSTOMER_UUID` | From the `rel: "customer"` link in the create response | | `CHANNEL_ID` | From `order.context.channelId` on any existing order | The `context` object with both `storeId` and `channelId` is mandatory for `addDraftOrder` and `updateOrder`. Retrieve the `channelId` from the Store REST endpoint: ```bash curl -s "https://api.godaddy.com/v1/commerce/stores/${STORE_ID}" \ -H "Authorization: Bearer $GODADDY_PAT" | jq '.defaultChannelId' ``` The `defaultChannelId` field is available on every store, including new stores with no orders. The value is stable — use it for all orders in the store. # How to process an order (https://developer.godaddy.com/en/docs/api-users/commerce/manage-orders-and-customers) --- title: How to process an order description: >- Create, manage, and complete orders through the Order GraphQL subgraph — all order lifecycle operations from draft through fulfillment. keywords: >- orderId, DRAFT OPEN CLOSED CANCELLED, createOrder, openOrder, addLineItem, lineItem total, commerce.order scope, order lifecycle states agentNotes: permissions: [] scopes: - 'commerce.order:read' - 'commerce.order:create' - 'commerce.order:update' - 'commerce.order:complete' - 'commerce.order:cancel' idempotent: false destructive: false failureRecovery: >- Query operations are safe to retry. For mutations, check the current order state with orderById before retrying — re-creating a draft can produce duplicate orders. related: apis: - title: Order GraphQL reference href: /docs/references/rest/orders guides: - title: Manage a store href: /docs/api-users/commerce/set-up-a-store - title: List sales channels href: /docs/api-users/commerce/set-up-a-store/channel - title: Manage catalog items href: /docs/api-users/commerce/manage-catalog - title: Manage a customer href: /docs/api-users/commerce/manage-orders-and-customers/customer concepts: - title: About the Commerce API href: /docs/api-users/commerce - title: Authentication href: /docs/api-users/auth - title: Rate limits href: /docs/api-users/rate-limits - title: Paginate results href: /docs/api-users/pagination --- ## Overview The Order subgraph manages orders through their full lifecycle: `DRAFT` to `OPEN` to `COMPLETED` (or `CANCELED`). All operations (reads, creates, and status transitions) are GraphQL queries and mutations sent to `POST /v1/commerce/order-subgraph`. This endpoint requires an `x-store-id` header to select the store; it doesn't take a `storeId` path parameter. Mutations that take an input object also include the store context as `context.storeId`; `id`-only mutations (for example, `cancelOrder`) rely on the header alone. The following article provides examples of how to use the Order subgraph to manage orders in your store. The Order subgraph has no `Idempotency-Key` header, but creates are still safe to retry when you supply your own identifiers. With `addOrderWithId`, the service enforces uniqueness on both the `id` you generate and your optional `externalId` (unique per channel), so replaying the same create is rejected instead of producing a duplicate. After a network timeout, confirm the result before resending: look the order up with `orderById`, or with `orderByExternalId` (which also requires the `channelId`). Resend only if the order didn't land. Creates where the service assigns the id (like `addDraftOrder`) don't have this safeguard, so a blind retry can create a second order. ## Prerequisites The following prerequisites are required before you can process orders: * a GoDaddy account with an active commerce store * a [Personal Access Token (PAT)](https://developer.godaddy.com/docs/api-users/auth) with the scopes for the operations you need (`commerce.order:read` for queries; `commerce.order:create`, `:update`, `:complete`, or `:cancel` for the corresponding mutations) * your `storeId` Go to [Your stores](https://developer.godaddy.com/docs/api-users/commerce#your-stores) to find your store ID. * your `channelId` (required to create orders) Go to [List sales channels](https://developer.godaddy.com/docs/api-users/commerce/set-up-a-store/channel) to retrieve the `channelId` for your store. ## List orders `orders(first, after)` returns a paginated list of orders. Go to [Paginate results](https://developer.godaddy.com/docs/api-users/pagination) for cursor-based pagination guidance. The following procedure retrieves the first page of orders. 1. Query the first 10 orders: ```bash tab="curl" curl -s -X POST "https://api.godaddy.com/v1/commerce/order-subgraph" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "Content-Type: application/json" \ -H "x-store-id: $STORE_ID" \ -d '{"query": "{ orders(first: 10) { edges { node { id number statuses { status } totals { total { value currencyCode } } } } pageInfo { hasNextPage endCursor } } }"}' ``` ```js tab="Node" const token = process.env.GODADDY_PAT; const res = await fetch("https://api.godaddy.com/v1/commerce/order-subgraph", { method: "POST", headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", "x-store-id": process.env.STORE_ID, }, body: JSON.stringify({ query: `{ orders(first: 10) { edges { node { id number statuses { status } totals { total { value currencyCode } } } } pageInfo { hasNextPage endCursor } } }`, }), }); const data = await res.json(); console.log(data.data.orders); ``` ```python tab="Python" import os, requests token = os.environ["GODADDY_PAT"] res = requests.post( "https://api.godaddy.com/v1/commerce/order-subgraph", headers={ "Authorization": f"Bearer {token}", "Content-Type": "application/json", "x-store-id": os.environ["STORE_ID"], }, json={ "query": "{ orders(first: 10) { edges { node { id number statuses { status } totals { total { value currencyCode } } } } pageInfo { hasNextPage endCursor } } }" }, ) res.raise_for_status() print(res.json()["data"]["orders"]) ``` ```go tab="Go" package main import ( "bytes" "encoding/json" "fmt" "net/http" "os" ) func main() { token := os.Getenv("GODADDY_PAT") payload := map[string]any{ "query": `{ orders(first: 10) { edges { node { id number statuses { status } totals { total { value currencyCode } } } } pageInfo { hasNextPage endCursor } } }`, } body, _ := json.Marshal(payload) req, _ := http.NewRequest("POST", "https://api.godaddy.com/v1/commerce/order-subgraph", bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer "+token) req.Header.Set("Content-Type", "application/json") req.Header.Set("x-store-id", os.Getenv("STORE_ID")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() var result map[string]any json.NewDecoder(res.Body).Decode(&result) fmt.Println(result) } ``` 2. Review the paginated response: ```json { "data": { "orders": { "edges": [ { "node": { "id": "", "number": "", "statuses": { "status": "" }, "totals": { "total": { "value": 550, "currencyCode": "USD" } } } } ], "pageInfo": { "hasNextPage": true, "endCursor": "" } } } } ``` ## Get an order `orderById(id: ID!)` retrieves a single order by its ID. The following procedure reads a single order by ID. * Retrieve an order by its `id`: ```bash tab="curl" ORDER_ID="" curl -s -X POST "https://api.godaddy.com/v1/commerce/order-subgraph" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "Content-Type: application/json" \ -H "x-store-id: $STORE_ID" \ -d "{\"query\": \"query { orderById(id: \\\"${ORDER_ID}\\\") { id number statuses { status } totals { total { value currencyCode } } createdAt } }\"}" ``` ```js tab="Node" const token = process.env.GODADDY_PAT; const orderId = ""; const res = await fetch("https://api.godaddy.com/v1/commerce/order-subgraph", { method: "POST", headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", "x-store-id": process.env.STORE_ID, }, body: JSON.stringify({ query: `query OrderById($id: ID!) { orderById(id: $id) { id number statuses { status } totals { total { value currencyCode } } createdAt } }`, variables: { id: orderId }, }), }); const data = await res.json(); console.log(data.data.orderById); ``` ```python tab="Python" import os, requests token = os.environ["GODADDY_PAT"] order_id = "" res = requests.post( "https://api.godaddy.com/v1/commerce/order-subgraph", headers={ "Authorization": f"Bearer {token}", "Content-Type": "application/json", "x-store-id": os.environ["STORE_ID"], }, json={ "query": "query OrderById($id: ID!) { orderById(id: $id) { id number statuses { status } totals { total { value currencyCode } } createdAt } }", "variables": {"id": order_id}, }, ) res.raise_for_status() print(res.json()["data"]["orderById"]) ``` ```go tab="Go" package main import ( "bytes" "encoding/json" "fmt" "net/http" "os" ) func main() { token := os.Getenv("GODADDY_PAT") orderId := "" payload := map[string]any{ "query": `query OrderById($id: ID!) { orderById(id: $id) { id number statuses { status } totals { total { value currencyCode } } createdAt } }`, "variables": map[string]any{"id": orderId}, } body, _ := json.Marshal(payload) req, _ := http.NewRequest("POST", "https://api.godaddy.com/v1/commerce/order-subgraph", bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer "+token) req.Header.Set("Content-Type", "application/json") req.Header.Set("x-store-id", os.Getenv("STORE_ID")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() var result map[string]any json.NewDecoder(res.Body).Decode(&result) fmt.Println(result) } ``` ## Create a draft order `addDraftOrder(input: AddDraftOrderInput!)` creates a new order in `DRAFT` status. The only required input is `context`, which must include both `storeId` and `channelId`. Save the returned `id`. The returned `id` is required for all subsequent order operations. The following procedure creates a draft order for a specific store and channel. 1. Create a draft order: ```bash tab="curl" curl -s -X POST "https://api.godaddy.com/v1/commerce/order-subgraph" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "Content-Type: application/json" \ -H "x-store-id: $STORE_ID" \ -d '{ "query": "mutation AddDraftOrder($input: AddDraftOrderInput!) { addDraftOrder(input: $input) { id number customerId statuses { status } } }", "variables": { "input": { "context": { "storeId": "", "channelId": "" }, "customerId": "" } } }' ``` ```js tab="Node" const token = process.env.GODADDY_PAT; const storeId = process.env.STORE_ID; const channelId = ""; const customerId = ""; const res = await fetch("https://api.godaddy.com/v1/commerce/order-subgraph", { method: "POST", headers: { "Authorization": `Bearer ${token}`, "Content-Type": "application/json", "x-store-id": process.env.STORE_ID, }, body: JSON.stringify({ query: `mutation AddDraftOrder($input: AddDraftOrderInput!) { addDraftOrder(input: $input) { id number customerId statuses { status } } }`, variables: { input: { context: { storeId, channelId }, customerId, }, }, }), }); const data = await res.json(); console.log(data.data.addDraftOrder); ``` ```python tab="Python" import os, requests token = os.environ["GODADDY_PAT"] store_id = os.environ["STORE_ID"] channel_id = "" customer_id = "" res = requests.post( "https://api.godaddy.com/v1/commerce/order-subgraph", headers={ "Authorization": f"Bearer {token}", "Content-Type": "application/json", "x-store-id": os.environ["STORE_ID"], }, json={ "query": "mutation AddDraftOrder($input: AddDraftOrderInput!) { addDraftOrder(input: $input) { id number customerId statuses { status } } }", "variables": { "input": { "context": { "storeId": store_id, "channelId": channel_id, }, "customerId": customer_id, } }, }, ) res.raise_for_status() print(res.json()["data"]["addDraftOrder"]) ``` ```go tab="Go" package main import ( "bytes" "encoding/json" "fmt" "net/http" "os" ) func main() { token := os.Getenv("GODADDY_PAT") storeId := os.Getenv("STORE_ID") channelId := "" customerId := "" payload := map[string]any{ "query": `mutation AddDraftOrder($input: AddDraftOrderInput!) { addDraftOrder(input: $input) { id number customerId statuses { status } } }`, "variables": map[string]any{ "input": map[string]any{ "context": map[string]any{ "storeId": storeId, "channelId": channelId, }, "customerId": customerId, }, }, } body, _ := json.Marshal(payload) req, _ := http.NewRequest("POST", "https://api.godaddy.com/v1/commerce/order-subgraph", bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer "+token) req.Header.Set("Content-Type", "application/json") req.Header.Set("x-store-id", os.Getenv("STORE_ID")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() var result map[string]any json.NewDecoder(res.Body).Decode(&result) fmt.Println(result) } ``` 2. To verify the customer was attached, include `customerId` in the response. Go to the [Orders API reference](https://developer.godaddy.com/docs/references/rest/orders) for all optional input fields available on order creation mutations. 3. Save the `id` from the response (you'll need it for every subsequent mutation on this order): ```json { "data": { "addDraftOrder": { "id": "", "number": "", "customerId": "", "statuses": { "status": "DRAFT" } } } } ``` ## Add a line item `addLineItemBySkuId(input: AddLineItemInput!)` adds a catalog SKU to an existing order. The `orderId` is in the format `Order_` returned from `addDraftOrder`. Both `fulfillmentMode` and `status` are required. The following procedure adds a SKU to a draft order. 1. Add a line item by SKU ID (using the `id` from step 3 above): ```bash tab="curl" curl -s -X POST "https://api.godaddy.com/v1/commerce/order-subgraph" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "Content-Type: application/json" \ -H "x-store-id: $STORE_ID" \ -d '{ "query": "mutation AddLineItem($input: AddLineItemInput!) { addLineItemBySkuId(input: $input) { id name status } }", "variables": { "input": { "orderId": "", "skuId": "", "quantity": 1, "fulfillmentMode": "NONE", "status": "UNFULFILLED" } } }' ``` ```js tab="Node" const token = process.env.GODADDY_PAT; const orderId = ""; const skuId = ""; const res = await fetch("https://api.godaddy.com/v1/commerce/order-subgraph", { method: "POST", headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", "x-store-id": process.env.STORE_ID, }, body: JSON.stringify({ query: `mutation AddLineItem($input: AddLineItemInput!) { addLineItemBySkuId(input: $input) { id name status } }`, variables: { input: { orderId, skuId, quantity: 1, fulfillmentMode: "NONE", status: "UNFULFILLED", }, }, }), }); const data = await res.json(); console.log(data.data.addLineItemBySkuId); ``` ```python tab="Python" import os, requests token = os.environ["GODADDY_PAT"] order_id = "" sku_id = "" res = requests.post( "https://api.godaddy.com/v1/commerce/order-subgraph", headers={ "Authorization": f"Bearer {token}", "Content-Type": "application/json", "x-store-id": os.environ["STORE_ID"], }, json={ "query": "mutation AddLineItem($input: AddLineItemInput!) { addLineItemBySkuId(input: $input) { id name status } }", "variables": { "input": { "orderId": order_id, "skuId": sku_id, "quantity": 1, "fulfillmentMode": "NONE", "status": "UNFULFILLED", } }, }, ) res.raise_for_status() print(res.json()["data"]["addLineItemBySkuId"]) ``` ```go tab="Go" package main import ( "bytes" "encoding/json" "fmt" "net/http" "os" ) func main() { token := os.Getenv("GODADDY_PAT") orderId := "" skuId := "" payload := map[string]any{ "query": `mutation AddLineItem($input: AddLineItemInput!) { addLineItemBySkuId(input: $input) { id name status } }`, "variables": map[string]any{ "input": map[string]any{ "orderId": orderId, "skuId": skuId, "quantity": 1, "fulfillmentMode": "NONE", "status": "UNFULFILLED", }, }, } body, _ := json.Marshal(payload) req, _ := http.NewRequest("POST", "https://api.godaddy.com/v1/commerce/order-subgraph", bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer "+token) req.Header.Set("Content-Type", "application/json") req.Header.Set("x-store-id", os.Getenv("STORE_ID")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() var result map[string]any json.NewDecoder(res.Body).Decode(&result) fmt.Println(result) } ``` 2. Review the returned line item: ```json { "data": { "addLineItemBySkuId": { "id": "", "name": "", "status": "UNFULFILLED" } } } ``` The `fulfillmentMode` field accepts any `LineItemModeInput` value: `NONE`, `PICKUP`, `SHIP`, `CURBSIDE`, `DELIVERY`, `DRIVE_THRU`, `FOR_HERE`, `TO_GO`, `DIGITAL`, `PURCHASE`, `GENERAL_CONTAINER`, `QUICK_STAY`, `REGULAR_STAY`, `NON_LODGING_NRR`, `NON_LODGING_SALE`, or `GIFT_CARD`. The `status` field accepts any `LineItemStatusInput` value: `UNFULFILLED`, `ON_HOLD`, `IN_PROGRESS`, `CONFIRMED`, `AWAITING`, `PARTIALLY_FULFILLED`, `FULFILLED`, `PARTIALLY_RETURNED`, `RETURNED`, `CANCELED`, or `DRAFT`. ## Open an order `openOrder(id: ID!)` transitions a `DRAFT` order to `OPEN` status. The draft must have at least one line item. `cancelOrder`, `completeOrder`, and `refundOrder` apply to non-draft orders (`OPEN` / completed as documented on each mutation). Use `updateDraftOrder` for drafts (`updateOrder` is rejected on drafts). `filterOrders(status: [DRAFT])` can list drafts. `addOrder` / `addOrderWithId` use `OrderStatusInput`, which is only `OPEN`, `COMPLETED`, or `CANCELED` (not `DRAFT`). Those mutations also require a full `OrderTotalsInput` (`subTotal`, `shippingTotal`, `discountTotal`, `feeTotal`, `taxTotal`, `total`). The following procedure opens a draft order. 1. Open the draft order: ```bash tab="curl" ORDER_ID="" curl -s -X POST "https://api.godaddy.com/v1/commerce/order-subgraph" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "Content-Type: application/json" \ -H "x-store-id: $STORE_ID" \ -d "{\"query\": \"mutation OpenOrder(\$id: ID!) { openOrder(id: \$id) { id statuses { status } } }\", \"variables\": {\"id\": \"${ORDER_ID}\"}}" ``` ```js tab="Node" const token = process.env.GODADDY_PAT; const orderId = ""; const res = await fetch("https://api.godaddy.com/v1/commerce/order-subgraph", { method: "POST", headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", "x-store-id": process.env.STORE_ID, }, body: JSON.stringify({ query: `mutation OpenOrder($id: ID!) { openOrder(id: $id) { id statuses { status } } }`, variables: { id: orderId }, }), }); const data = await res.json(); console.log(data.data.openOrder); ``` ```python tab="Python" import os, requests token = os.environ["GODADDY_PAT"] order_id = "" res = requests.post( "https://api.godaddy.com/v1/commerce/order-subgraph", headers={ "Authorization": f"Bearer {token}", "Content-Type": "application/json", "x-store-id": os.environ["STORE_ID"], }, json={ "query": "mutation OpenOrder($id: ID!) { openOrder(id: $id) { id statuses { status } } }", "variables": {"id": order_id}, }, ) res.raise_for_status() print(res.json()["data"]["openOrder"]) ``` ```go tab="Go" package main import ( "bytes" "encoding/json" "fmt" "net/http" "os" ) func main() { token := os.Getenv("GODADDY_PAT") orderId := "" payload := map[string]any{ "query": `mutation OpenOrder($id: ID!) { openOrder(id: $id) { id statuses { status } } }`, "variables": map[string]any{"id": orderId}, } body, _ := json.Marshal(payload) req, _ := http.NewRequest("POST", "https://api.godaddy.com/v1/commerce/order-subgraph", bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer "+token) req.Header.Set("Content-Type", "application/json") req.Header.Set("x-store-id", os.Getenv("STORE_ID")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() var result map[string]any json.NewDecoder(res.Body).Decode(&result) fmt.Println(result) } ``` 2. Confirm the order status updated to `OPEN`: ```json { "data": { "openOrder": { "id": "", "statuses": { "status": "OPEN" } } } } ``` ## Complete an order `completeOrder(id: ID!)` marks an `OPEN` order as `COMPLETED`. Only `OPEN` orders can be completed. The following procedure completes an open order. 1. Complete the order: ```bash tab="curl" ORDER_ID="" curl -s -X POST "https://api.godaddy.com/v1/commerce/order-subgraph" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "Content-Type: application/json" \ -H "x-store-id: $STORE_ID" \ -d "{\"query\": \"mutation CompleteOrder(\$id: ID!) { completeOrder(id: \$id) { id statuses { status } } }\", \"variables\": {\"id\": \"${ORDER_ID}\"}}" ``` ```js tab="Node" const token = process.env.GODADDY_PAT; const orderId = ""; const res = await fetch("https://api.godaddy.com/v1/commerce/order-subgraph", { method: "POST", headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", "x-store-id": process.env.STORE_ID, }, body: JSON.stringify({ query: `mutation CompleteOrder($id: ID!) { completeOrder(id: $id) { id statuses { status } } }`, variables: { id: orderId }, }), }); const data = await res.json(); console.log(data.data.completeOrder); ``` ```python tab="Python" import os, requests token = os.environ["GODADDY_PAT"] order_id = "" res = requests.post( "https://api.godaddy.com/v1/commerce/order-subgraph", headers={ "Authorization": f"Bearer {token}", "Content-Type": "application/json", "x-store-id": os.environ["STORE_ID"], }, json={ "query": "mutation CompleteOrder($id: ID!) { completeOrder(id: $id) { id statuses { status } } }", "variables": {"id": order_id}, }, ) res.raise_for_status() print(res.json()["data"]["completeOrder"]) ``` ```go tab="Go" package main import ( "bytes" "encoding/json" "fmt" "net/http" "os" ) func main() { token := os.Getenv("GODADDY_PAT") orderId := "" payload := map[string]any{ "query": `mutation CompleteOrder($id: ID!) { completeOrder(id: $id) { id statuses { status } } }`, "variables": map[string]any{"id": orderId}, } body, _ := json.Marshal(payload) req, _ := http.NewRequest("POST", "https://api.godaddy.com/v1/commerce/order-subgraph", bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer "+token) req.Header.Set("Content-Type", "application/json") req.Header.Set("x-store-id", os.Getenv("STORE_ID")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() var result map[string]any json.NewDecoder(res.Body).Decode(&result) fmt.Println(result) } ``` 2. Confirm the order status updated to `COMPLETED`: ```json { "data": { "completeOrder": { "id": "", "statuses": { "status": "COMPLETED" } } } } ``` ## Cancel an order `cancelOrder(id: ID!)` cancels an `OPEN` order. The following procedure cancels an open order. 1. Cancel the order: ```bash tab="curl" ORDER_ID="" curl -s -X POST "https://api.godaddy.com/v1/commerce/order-subgraph" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "Content-Type: application/json" \ -H "x-store-id: $STORE_ID" \ -d "{\"query\": \"mutation CancelOrder(\$id: ID!) { cancelOrder(id: \$id) { id statuses { status } } }\", \"variables\": {\"id\": \"${ORDER_ID}\"}}" ``` ```js tab="Node" const token = process.env.GODADDY_PAT; const orderId = ""; const res = await fetch("https://api.godaddy.com/v1/commerce/order-subgraph", { method: "POST", headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", "x-store-id": process.env.STORE_ID, }, body: JSON.stringify({ query: `mutation CancelOrder($id: ID!) { cancelOrder(id: $id) { id statuses { status } } }`, variables: { id: orderId }, }), }); const data = await res.json(); console.log(data.data.cancelOrder); ``` ```python tab="Python" import os, requests token = os.environ["GODADDY_PAT"] order_id = "" res = requests.post( "https://api.godaddy.com/v1/commerce/order-subgraph", headers={ "Authorization": f"Bearer {token}", "Content-Type": "application/json", "x-store-id": os.environ["STORE_ID"], }, json={ "query": "mutation CancelOrder($id: ID!) { cancelOrder(id: $id) { id statuses { status } } }", "variables": {"id": order_id}, }, ) res.raise_for_status() print(res.json()["data"]["cancelOrder"]) ``` ```go tab="Go" package main import ( "bytes" "encoding/json" "fmt" "net/http" "os" ) func main() { token := os.Getenv("GODADDY_PAT") orderId := "" payload := map[string]any{ "query": `mutation CancelOrder($id: ID!) { cancelOrder(id: $id) { id statuses { status } } }`, "variables": map[string]any{"id": orderId}, } body, _ := json.Marshal(payload) req, _ := http.NewRequest("POST", "https://api.godaddy.com/v1/commerce/order-subgraph", bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer "+token) req.Header.Set("Content-Type", "application/json") req.Header.Set("x-store-id", os.Getenv("STORE_ID")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() var result map[string]any json.NewDecoder(res.Body).Decode(&result) fmt.Println(result) } ``` 2. Confirm the order status updated to `CANCELED`: ```json { "data": { "cancelOrder": { "id": "", "statuses": { "status": "CANCELED" } } } } ``` ## Common errors The following table lists common errors when processing orders, the most likely cause, and additional notes: | Status | Most likely cause | Note | | ------ | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `400` | Malformed GraphQL query, or missing required input field. | `Order` has `statuses { status }`, not `status`. List connections use `edges { node }`, not `nodes`. `Money` fields need `{ value currencyCode }`. | | `401` | PAT is missing or expired. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) to generate a new token. | | `403` | Token doesn't include the scope for the requested operation. | Ensure your PAT includes the required scopes for the operation. | | `404` | Order ID doesn't exist or isn't accessible with the provided token. | | | `422` | Invalid status transition. | For example, cancel/complete/refund a `DRAFT`, or `openOrder` with no line items. | | `429` | Rate limit exceeded. | Honor the `Retry-After` header before retrying. | # How to view transactions (https://developer.godaddy.com/en/docs/api-users/commerce/manage-orders-and-customers/transaction) --- title: How to view transactions description: >- Look up payment transaction history for a store — authorizations, captures, sales, refunds, and adjustments. keywords: >- transactionId, AUTHORIZATION CAPTURE SALE REFUND ADJUSTMENT, listTransactions, getTransaction, transaction type, payment record, commerce.transaction scope agentNotes: permissions: [] scopes: - 'commerce.transaction:read' idempotent: true destructive: false failureRecovery: Safe to retry on any error. Transaction reads are idempotent. related: apis: - title: Transaction API reference href: /docs/references/rest/transactions/get-transactions guides: - title: Process an order href: /docs/api-users/commerce/manage-orders-and-customers - title: Manage a store href: /docs/api-users/commerce/set-up-a-store concepts: - title: About the Commerce API href: /docs/api-users/commerce - title: Authentication href: /docs/api-users/auth - title: Rate limits href: /docs/api-users/rate-limits --- ## Overview Transactions represent payment activity associated with orders: authorizations, captures, sales, refunds, and adjustments. The Transaction API is a read-only REST API under `v2` (this differs from the other Commerce REST endpoints which use `v1`). ## Prerequisites The following prerequisites are required before you view transactions: * a GoDaddy account with an active commerce store * a [Personal Access Token (PAT)](https://developer.godaddy.com/docs/api-users/auth) with the `commerce.transaction:read` scope * your `storeId` Go to [Your stores](https://developer.godaddy.com/docs/api-users/commerce#your-stores) to find your store ID. ## List transactions `GET /v2/commerce/stores/{storeId}/transactions` retrieves all transactions for a store. The following optional query parameters narrow the results: | Parameter | Type | Description | | ----------------- | -------- | ------------------------------------------------- | | `page` | integer | Page number to retrieve (default: `1`) | | `pageSize` | integer | Results per page (default: `10`) | | `totalRequired` | boolean | Include total count in the response | | `transactionIds` | string | Comma-separated transaction IDs to filter | | `updatedAtAfter` | datetime | Filter transactions updated after this timestamp | | `updatedAtBefore` | datetime | Filter transactions updated before this timestamp | | `sortBy` | string | Field to sort by (`updatedAt`) | | `sortOrder` | string | Sort direction (`ASC` or `DESC`, default: `ASC`) | The following procedure lists the most recent 20 transactions. 1. Retrieve a page of transactions: ```bash tab="curl" curl -s "https://api.godaddy.com/v2/commerce/stores/${STORE_ID}/transactions?pageSize=20&sortOrder=DESC" \ -H "Authorization: Bearer $GODADDY_PAT" ``` ```js tab="Node" const token = process.env.GODADDY_PAT; const storeId = process.env.STORE_ID; const params = new URLSearchParams({ pageSize: "20", sortOrder: "DESC" }); const res = await fetch( `https://api.godaddy.com/v2/commerce/stores/${storeId}/transactions?${params}`, { headers: { Authorization: `Bearer ${token}` } } ); const data = await res.json(); console.log(data); ``` ```python tab="Python" import os, requests token = os.environ["GODADDY_PAT"] store_id = os.environ["STORE_ID"] res = requests.get( f"https://api.godaddy.com/v2/commerce/stores/{store_id}/transactions", params={"pageSize": 20, "sortOrder": "DESC"}, headers={"Authorization": f"Bearer {token}"}, ) res.raise_for_status() print(res.json()) ``` ```go tab="Go" package main import ( "encoding/json" "fmt" "net/http" "os" ) func main() { token := os.Getenv("GODADDY_PAT") storeId := os.Getenv("STORE_ID") url := fmt.Sprintf( "https://api.godaddy.com/v2/commerce/stores/%s/transactions?pageSize=20&sortOrder=DESC", storeId, ) req, _ := http.NewRequest("GET", url, nil) req.Header.Set("Authorization", "Bearer "+token) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() var result map[string]any json.NewDecoder(res.Body).Decode(&result) fmt.Println(result) } ``` 2. Review the response including the paginated list of transactions: ```json { "items": [ { "id": "", "orderId": "", "type": "", "status": "", "amount": { "value": "", "currency": "" }, "createdAt": "", "updatedAt": "" } ], "page": 1, "pageSize": 20 } ``` ## Get a transaction `GET /v2/commerce/stores/{storeId}/transactions/{transactionId}` retrieves a single transaction by ID. The following procedure reads a single transaction by ID. * Retrieve a single transaction by its `id`: ```bash tab="curl" TRANSACTION_ID="" curl -s "https://api.godaddy.com/v2/commerce/stores/${STORE_ID}/transactions/${TRANSACTION_ID}" \ -H "Authorization: Bearer $GODADDY_PAT" ``` ```js tab="Node" const token = process.env.GODADDY_PAT; const storeId = process.env.STORE_ID; const transactionId = ""; const res = await fetch( `https://api.godaddy.com/v2/commerce/stores/${storeId}/transactions/${transactionId}`, { headers: { Authorization: `Bearer ${token}` } } ); const transaction = await res.json(); console.log(transaction); ``` ```python tab="Python" import os, requests token = os.environ["GODADDY_PAT"] store_id = os.environ["STORE_ID"] transaction_id = "" res = requests.get( f"https://api.godaddy.com/v2/commerce/stores/{store_id}/transactions/{transaction_id}", headers={"Authorization": f"Bearer {token}"}, ) res.raise_for_status() print(res.json()) ``` ```go tab="Go" package main import ( "encoding/json" "fmt" "net/http" "os" ) func main() { token := os.Getenv("GODADDY_PAT") storeId := os.Getenv("STORE_ID") transactionId := "" url := fmt.Sprintf("https://api.godaddy.com/v2/commerce/stores/%s/transactions/%s", storeId, transactionId) req, _ := http.NewRequest("GET", url, nil) req.Header.Set("Authorization", "Bearer "+token) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() var transaction map[string]any json.NewDecoder(res.Body).Decode(&transaction) fmt.Println(transaction) } ``` ## Common errors The following table lists common errors when viewing transactions, the most likely cause, and additional notes: | Status | Most likely cause | Note | | ------ | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | | `401` | PAT is missing or expired. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) to generate a new token. | | `403` | Token doesn't include the `commerce.transaction:read` scope. | | | `404` | Store ID or transaction ID doesn't exist or isn't accessible with the provided token. | | | `429` | Rate limit exceeded. | Honor the `Retry-After` header before retrying. | # How to list sales channels (https://developer.godaddy.com/en/docs/api-users/commerce/set-up-a-store/channel) --- title: How to list sales channels description: >- Query the sales channels registered to a store — online, POS, mobile, and more. keywords: >- channelId, ONLINE POS MOBILE channel type, listChannels, getChannel, point of sale, storefront, commerce.channel scope agentNotes: permissions: [] scopes: - 'commerce.channel:read' idempotent: true destructive: false failureRecovery: Safe to retry on any error. Channel reads are idempotent. related: apis: - title: Channel API reference href: /docs/references/rest/channels/get-channels guides: - title: Manage a store href: /docs/api-users/commerce/set-up-a-store concepts: - title: Commerce core concepts href: /docs/api-users/commerce/concepts - title: Authentication href: /docs/api-users/auth - title: Rate limits href: /docs/api-users/rate-limits --- ## Overview Channels represent the surfaces customers can buy from (like an online store, a point-of-sale terminal, a mobile app, or a third-party marketplace). This page covers how to list and read sales channels for a store. ## Prerequisites The following prerequisites are required before you can list sales channels for a store: * a GoDaddy account with an active commerce store * a [Personal Access Token (PAT)](https://developer.godaddy.com/docs/api-users/auth) with the `commerce.channel:read` scope * your `storeId` Go to [Your stores](https://developer.godaddy.com/docs/api-users/commerce#your-stores) to find your store ID. ## List channels `GET /v1/commerce/channels` retrieves sales channels matching the supplied filter. Include at least one of these query parameters: `registeredStores.storeId` (filter by store) or `externalChannelId` (filter by the channel's external ID). A request with neither returns `400 INVALID_REQUEST`. The following procedure lists channels registered to a specific store using `registeredStores.storeId`: 1. Retrieve a list of channels registered to a specific store: ```bash tab="curl" curl -s "https://api.godaddy.com/v1/commerce/channels?registeredStores.storeId=${STORE_ID}" \ -H "Authorization: Bearer $GODADDY_PAT" ``` ```js tab="Node" const token = process.env.GODADDY_PAT; const storeId = process.env.STORE_ID; const res = await fetch( `https://api.godaddy.com/v1/commerce/channels?registeredStores.storeId=${storeId}`, { headers: { Authorization: `Bearer ${token}` } } ); const channels = await res.json(); console.log(channels); ``` ```python tab="Python" import os, requests token = os.environ["GODADDY_PAT"] store_id = os.environ["STORE_ID"] res = requests.get( "https://api.godaddy.com/v1/commerce/channels", params={"registeredStores.storeId": store_id}, headers={"Authorization": f"Bearer {token}"}, ) res.raise_for_status() for channel in res.json(): print(channel["id"], channel["name"], channel["type"]) ``` ```go tab="Go" package main import ( "encoding/json" "fmt" "net/http" "os" ) func main() { token := os.Getenv("GODADDY_PAT") storeId := os.Getenv("STORE_ID") url := fmt.Sprintf("https://api.godaddy.com/v1/commerce/channels?registeredStores.storeId=%s", storeId) req, _ := http.NewRequest("GET", url, nil) req.Header.Set("Authorization", "Bearer "+token) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() var channels []map[string]any json.NewDecoder(res.Body).Decode(&channels) fmt.Println(channels) } ``` 2. Review the response array of channel objects: ```json [ { "id": "", "name": "", "type": "", "status": "", "storeId": "", "createdAt": "", "updatedAt": "" }, { "id": "", "name": "", "type": "", "status": "", "storeId": "", "createdAt": "", "updatedAt": "" } ] ``` ## Get channel by ID `GET /v1/commerce/channels/{channelId}` retrieves a specific sales channel. PAT callers with store-level `commerce.channel:read` often receive `401` on this route because the service requires a per-resource FGA relation. List channels for the store and filter instead: ```bash curl -s "https://api.godaddy.com/v1/commerce/channels?registeredStores.storeId=${STORE_ID}" \ -H "Authorization: Bearer $GODADDY_PAT" \ | jq '.items[] | select(.channelId == "")' ``` That returns the full channel object. The get-by-id examples below are the documented route; use the list workaround when get-by-id returns `401`. The following procedure reads a single channel by ID. * Retrieve a single channel by its `id`: ```bash tab="curl" CHANNEL_ID="" curl -s "https://api.godaddy.com/v1/commerce/channels/${CHANNEL_ID}" \ -H "Authorization: Bearer $GODADDY_PAT" ``` ```js tab="Node" const token = process.env.GODADDY_PAT; const channelId = ""; const res = await fetch( `https://api.godaddy.com/v1/commerce/channels/${channelId}`, { headers: { Authorization: `Bearer ${token}` } } ); const channel = await res.json(); console.log(channel); ``` ```python tab="Python" import os, requests token = os.environ["GODADDY_PAT"] channel_id = "" res = requests.get( f"https://api.godaddy.com/v1/commerce/channels/{channel_id}", headers={"Authorization": f"Bearer {token}"}, ) res.raise_for_status() print(res.json()) ``` ```go tab="Go" package main import ( "encoding/json" "fmt" "net/http" "os" ) func main() { token := os.Getenv("GODADDY_PAT") channelId := "" url := fmt.Sprintf("https://api.godaddy.com/v1/commerce/channels/%s", channelId) req, _ := http.NewRequest("GET", url, nil) req.Header.Set("Authorization", "Bearer "+token) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() var channel map[string]any json.NewDecoder(res.Body).Decode(&channel) fmt.Println(channel) } ``` ## Channel types Each channel has a `type` from the Channels API enum. Use `subType` for product-specific detail (for example, a marketplace provider or website product); `subType` is set when the channel is registered and cannot be changed. | Type | Description | | ------------- | -------------------------------------------------------------------------------------------------------------- | | `RETAIL` | Physical retail location where merchant and customer transact in person (stores, pop-ups, food trucks) | | `ONLINE` | Web or online storefront sales | | `MOBILE` | Mobile app sales surface | | `MARKETPLACE` | External marketplace (for example Amazon or eBay) | | `SOCIAL` | Social commerce (for example Facebook or Instagram) | | `DEFAULT` | Platform default channel for the store; only one `DEFAULT` channel per store (often used for default payments) | ## Common errors | Status | Most likely cause | | ------ | -------------------------------------------------------------------------------------------------- | | `400` | Neither `registeredStores.storeId` nor `externalChannelId` was supplied. At least one is required. | | `401` | PAT is missing or expired. Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) to generate a new token. | | `403` | Token doesn't include the `commerce.channel:read` scope. | | `404` | Channel ID doesn't exist or isn't accessible with the provided token. | | `429` | Rate limit exceeded. Honor the `Retry-After` header before retrying. | # How to manage a store (https://developer.godaddy.com/en/docs/api-users/commerce/set-up-a-store) --- title: How to manage a store description: >- Find your store ID and read store configuration — required starting points for all Commerce API calls. keywords: >- storeId, getStore, storeAttribute, find store ID, commerce.store scope, store context, store setup agentNotes: permissions: [] scopes: - 'commerce.store:read' idempotent: true destructive: false failureRecovery: Safe to retry on any error. Store reads are idempotent. related: apis: - title: Store API reference href: /docs/references/rest/stores/get-store-by-id guides: - title: List sales channels href: /docs/api-users/commerce/set-up-a-store/channel concepts: - title: Commerce core concepts href: /docs/api-users/commerce/concepts - title: Authentication href: /docs/api-users/auth - title: Rate limits href: /docs/api-users/rate-limits --- ## Overview Every Commerce API call is scoped to a store. Your store ID (`storeId`) is a UUID you copy from the platform and pass in the path for every subsequent request. This page covers reading store configuration once you have a `storeId`. ## Prerequisites The following prerequisites are required before you can manage a store: * a [GoDaddy Payments](https://www.godaddy.com/payments) account with an active store Go to [Set up a GoDaddy Payments account](https://www.godaddy.com/help/get-started-with-godaddy-payments-40721) to create your account and activate your store. * a [Personal Access Token (PAT)](https://developer.godaddy.com/docs/api-users/auth) with the `commerce.store:read` scope * your `storeId` 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`. ## Get store by ID `GET /v1/commerce/stores/{storeId}` retrieves the configuration for a specific store. The following procedure reads the details of a store by ID. 1. Retrieve the details of a store by its `id`: ```bash tab="curl" curl -s "https://api.godaddy.com/v1/commerce/stores/${STORE_ID}" \ -H "Authorization: Bearer $GODADDY_PAT" ``` ```js tab="Node" const token = process.env.GODADDY_PAT; const storeId = process.env.STORE_ID; const res = await fetch( `https://api.godaddy.com/v1/commerce/stores/${storeId}`, { headers: { Authorization: `Bearer ${token}` } } ); const store = await res.json(); console.log(store); ``` ```python tab="Python" import os, requests token = os.environ["GODADDY_PAT"] store_id = os.environ["STORE_ID"] res = requests.get( f"https://api.godaddy.com/v1/commerce/stores/{store_id}", headers={"Authorization": f"Bearer {token}"}, ) res.raise_for_status() print(res.json()) ``` ```go tab="Go" package main import ( "encoding/json" "fmt" "net/http" "os" ) func main() { token := os.Getenv("GODADDY_PAT") storeId := os.Getenv("STORE_ID") url := fmt.Sprintf("https://api.godaddy.com/v1/commerce/stores/%s", storeId) req, _ := http.NewRequest("GET", url, nil) req.Header.Set("Authorization", "Bearer "+token) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() var store map[string]any json.NewDecoder(res.Body).Decode(&store) fmt.Println(store) } ``` 2. Review the response including the store ID, name, status, currency, and address: ```json { "id": "", "name": "", "status": "", "currency": "", "timezone": "", "address": { "line1": "", "city": "", "state": "", "postalCode": "", "country": "" }, "createdAt": "", "updatedAt": "" } ``` ## Get store attribute `GET /v1/commerce/stores/{storeId}/attributes/{attrName}` retrieves a single configuration attribute for a store. The following procedure reads one attribute by name. 1. Retrieve a single attribute by name: ```bash tab="curl" ATTR_NAME="" curl -s "https://api.godaddy.com/v1/commerce/stores/${STORE_ID}/attributes/${ATTR_NAME}" \ -H "Authorization: Bearer $GODADDY_PAT" ``` ```js tab="Node" const token = process.env.GODADDY_PAT; const storeId = process.env.STORE_ID; const attrName = ""; const res = await fetch( `https://api.godaddy.com/v1/commerce/stores/${storeId}/attributes/${attrName}`, { headers: { Authorization: `Bearer ${token}` } } ); const attr = await res.json(); console.log(attr); ``` ```python tab="Python" import os, requests token = os.environ["GODADDY_PAT"] store_id = os.environ["STORE_ID"] attr_name = "" res = requests.get( f"https://api.godaddy.com/v1/commerce/stores/{store_id}/attributes/{attr_name}", headers={"Authorization": f"Bearer {token}"}, ) res.raise_for_status() print(res.json()) ``` ```go tab="Go" package main import ( "encoding/json" "fmt" "net/http" "os" ) func main() { token := os.Getenv("GODADDY_PAT") storeId := os.Getenv("STORE_ID") attrName := "" url := fmt.Sprintf("https://api.godaddy.com/v1/commerce/stores/%s/attributes/%s", storeId, attrName) req, _ := http.NewRequest("GET", url, nil) req.Header.Set("Authorization", "Bearer "+token) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() var attr map[string]any json.NewDecoder(res.Body).Decode(&attr) fmt.Println(attr) } ``` 2. Review the response returning the attribute name and its current value: ```json { "name": "", "value": "" } ``` ## Common errors The following table lists common errors when reading store configuration and their most likely causes: | Status | Most likely cause | | ------ | ------------------------------------------------------------------------------------------------ | | `401` | PAT is missing or expired. Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) to generate a new token. | | `403` | Token doesn't include the `commerce.store:read` scope. | | `404` | Store ID doesn't exist or isn't accessible with the provided token. | | `429` | Rate limit exceeded. Honor the `Retry-After` header before retrying. | # How to manage DNS records (https://developer.godaddy.com/en/docs/api-users/domains/manage/dns) --- title: How to manage DNS records description: >- Manage DNS records and nameservers using the v3 API. Add, read, replace, and delete individual DNS records, and replace authoritative nameservers with a single PUT request. keywords: >- recordId, zone apex, A record, CNAME record, MX record, TXT record, SRV record, CAA record, SPF DKIM, wildcard DNS, dns-records endpoint. agentNotes: permissions: - DNS Management scopes: - 'domains.domain:read' - 'domains.dns:update' - 'domains.nameserver:update' idempotent: false destructive: true failureRecovery: >- Read operations are safe to retry. Deletes are irreversible. Confirm the recordId before calling DELETE. Re-read the zone after failures to verify state. related: apis: - title: 'Domains v3: DNS records' href: /docs/references/rest/domains/v3/list-dns-records guides: - title: Registered domains href: /docs/api-users/domains/manage/list - title: Forward a domain href: /docs/api-users/domains/manage/forwarding - title: Troubleshoot DNS href: /docs/api-users/troubleshoot/dns concepts: - title: Handle errors href: /docs/api-users/errors - title: Rate limits href: /docs/api-users/rate-limits --- ## Overview Create, read, replace, and delete DNS records for domains hosted on GoDaddy's authoritative nameservers, and replace the authoritative nameservers themselves. All operations use the v3 API. This page covers two related operations: | Operation | Description | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | **DNS records** | Create, retrieve, replace, and delete A, AAAA, CNAME, MX, TXT, SRV, NS, and CAA records on a domain hosted by GoDaddy's authoritative DNS. | | **Nameservers** | Change which authoritative nameservers the registry returns for a domain. | This page uses three OAuth scopes: `domains.domain:read` to list records, `domains.dns:update` to create, replace, and delete records, and `domains.nameserver:update` to replace nameservers. Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for more information. ## List DNS records `GET /v3/domains/zones/{zone}/dns-records` returns a paginated collection of records for the zone. Use `type` and `name` query parameters to filter results. The following procedure retrieves DNS records for a zone. * Run the following command for your preferred language: ```bash tab="curl" # All records curl -s "https://api.godaddy.com/v3/domains/zones/example.com/dns-records" \ -H "Authorization: Bearer $GODADDY_PAT" # Filter by type curl -s "https://api.godaddy.com/v3/domains/zones/example.com/dns-records?type=A" \ -H "Authorization: Bearer $GODADDY_PAT" # Filter by type and name curl -s "https://api.godaddy.com/v3/domains/zones/example.com/dns-records?type=TXT&name=_acme-challenge" \ -H "Authorization: Bearer $GODADDY_PAT" ``` ```js tab="Node" const pat = process.env.GODADDY_PAT; const zone = "example.com"; const url = new URL(`https://api.godaddy.com/v3/domains/zones/${zone}/dns-records`); url.searchParams.set("type", "TXT"); url.searchParams.set("name", "_acme-challenge"); const res = await fetch(url, { headers: { Authorization: `Bearer ${pat}` }, }); const records = await res.json(); console.log(records.items); ``` ```python tab="Python" import os, requests pat = os.environ["GODADDY_PAT"] zone = "example.com" res = requests.get( f"https://api.godaddy.com/v3/domains/zones/{zone}/dns-records", params={"type": "TXT", "name": "_acme-challenge"}, headers={"Authorization": f"Bearer {pat}"}, ) res.raise_for_status() for record in res.json()["items"]: print(record["name"], record["type"], record["data"]) ``` ```go tab="Go" package main import ( "encoding/json" "fmt" "net/http" "net/url" "os" ) func main() { pat := os.Getenv("GODADDY_PAT") zone := "example.com" u, _ := url.Parse(fmt.Sprintf("https://api.godaddy.com/v3/domains/zones/%s/dns-records", zone)) q := u.Query() q.Set("type", "TXT") q.Set("name", "_acme-challenge") u.RawQuery = q.Encode() req, _ := http.NewRequest("GET", u.String(), nil) req.Header.Set("Authorization", "Bearer "+pat) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() var body struct { Items []map[string]any `json:"items"` } json.NewDecoder(res.Body).Decode(&body) fmt.Println(body.Items) } ``` ```bash tab="CLI" gddy dns list example.com # Filter by type and name: gddy dns list example.com --type TXT --name _acme-challenge ``` The response is a `DNSRecords` object with an `items` array of `DNSRecord` entries. Each record includes a `recordId` needed for delete operations. Go to the [DNSRecord schema](#dnsrecord-schema) for the full field reference. ### DNSRecord schema Every entry in `items[]` is a `DNSRecord` object. | Field | Required | Description | Note | | ---------- | --------- | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- | | `recordId` | Read-only | Server-assigned stable identifier for the record. | | | `name` | Yes | Record name relative to the zone apex. | Use `@` for the apex. Wildcards (`*`) supported for A, AAAA, and CNAME. | | `type` | Yes | Record type: `A`, `AAAA`, `CNAME`, `MX`, `TXT`, `SRV`, `NS`, `CAA`, or `SOA` (SOA is read-only). | | | `data` | Yes | Record value. | Format depends on type: IP for A/AAAA, hostname for CNAME, text for TXT, etc. | | `ttl` | Yes | Time-to-live in seconds. | Minimum 600 (10 min), maximum 86400 (24 hrs). | | `priority` | MX, SRV | Priority value. | Lower value equals higher preference. | | `weight` | SRV | Relative weight among equal-priority targets. | | | `port` | SRV | Target port number. | | | `service` | SRV | Service name. | Prefixed with an underscore (for example, `_http`). | | `protocol` | SRV | Transport protocol. | Prefixed with underscore (for example, `_tcp`). | | `flag` | CAA | Restriction flags byte. | Use `0` for non-critical, `128` for critical. | | `tag` | CAA | Property tag: `issue`, `issuewild`, or `iodef`. | | ### Pagination Results are page-based. Use `page` (1-based, default `1`) and `pageSize` (1–100, default `25`) to navigate. The following procedure paginates through DNS records. * Navigate pages: ```bash curl -s "https://api.godaddy.com/v3/domains/zones/example.com/dns-records?page=2&pageSize=50" \ -H "Authorization: Bearer $GODADDY_PAT" ``` Add `totalRequired=true` to include `totalItems` and `totalPages` in the response — omitted by default to avoid count-query overhead on large zones. The response `links` array contains HATEOAS navigation links (`self`, `first`, `last`, `next`, `prev`) where applicable. ## Add a record `POST /v3/domains/zones/{zone}/dns-records` creates a single DNS record in the zone. Changes are applied synchronously — no polling required. The following procedure adds a DNS record to a zone. * Create a record: ```bash tab="curl" curl -s -X POST "https://api.godaddy.com/v3/domains/zones/example.com/dns-records" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "Content-Type: application/json" \ -d '{ "type": "TXT", "name": "_acme-challenge", "data": "verification-string", "ttl": 600 }' ``` ```js tab="Node" const pat = process.env.GODADDY_PAT; const zone = "example.com"; const res = await fetch( `https://api.godaddy.com/v3/domains/zones/${zone}/dns-records`, { method: "POST", headers: { Authorization: `Bearer ${pat}`, "Content-Type": "application/json", }, body: JSON.stringify({ type: "TXT", name: "_acme-challenge", data: "verification-string", ttl: 600 }), }, ); const record = await res.json(); console.log("Created record", record.recordId); ``` ```python tab="Python" import os, requests pat = os.environ["GODADDY_PAT"] zone = "example.com" res = requests.post( f"https://api.godaddy.com/v3/domains/zones/{zone}/dns-records", json={"type": "TXT", "name": "_acme-challenge", "data": "verification-string", "ttl": 600}, headers={ "Authorization": f"Bearer {pat}", "Content-Type": "application/json", }, ) res.raise_for_status() print("Created record", res.json()["recordId"]) ``` ```go tab="Go" package main import ( "bytes" "encoding/json" "fmt" "net/http" "os" ) func main() { pat := os.Getenv("GODADDY_PAT") zone := "example.com" body := bytes.NewReader([]byte( `{"type":"TXT","name":"_acme-challenge","data":"verification-string","ttl":600}`)) req, _ := http.NewRequest("POST", fmt.Sprintf("https://api.godaddy.com/v3/domains/zones/%s/dns-records", zone), body) req.Header.Set("Authorization", "Bearer "+pat) req.Header.Set("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() var record struct{ RecordID string `json:"recordId"` } json.NewDecoder(res.Body).Decode(&record) fmt.Println("Created record", record.RecordID) } ``` ```bash tab="CLI" gddy dns add example.com --type TXT --name _acme-challenge --data "verification-string" --ttl 600 ``` A successful response returns `201` with the created `DNSRecord` in the body. The `Location` header contains the URL for the new record, with the `recordId` you'll need for deletes. Replaying a `POST` after a `5xx` may create a duplicate record. Save the `recordId` from the `Location` header on success so you can clean up if needed. Go to [Errors → Retry semantics](https://developer.godaddy.com/docs/api-users/errors#retry-semantics). ## Replace a record `PUT /v3/domains/zones/{zone}/dns-records/{recordId}` fully replaces an existing DNS record. All writable fields — `name`, `type`, `data`, and `ttl` — must be supplied. Partial updates are not supported on this endpoint. Changes are applied synchronously. Every writable field must be present in the request body — omitted fields are not preserved. Read the record first if you need to keep any existing values. The following procedure replaces a DNS record. * Replace a record: ```bash tab="curl" curl -s -X PUT "https://api.godaddy.com/v3/domains/zones/example.com/dns-records/$RECORD_ID" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "Content-Type: application/json" \ -d '{ "name": "@", "type": "A", "data": "192.0.2.1", "ttl": 3600 }' ``` ```js tab="Node" const pat = process.env.GODADDY_PAT; const zone = "example.com"; const recordId = process.env.RECORD_ID; const res = await fetch( `https://api.godaddy.com/v3/domains/zones/${zone}/dns-records/${recordId}`, { method: "PUT", headers: { Authorization: `Bearer ${pat}`, "Content-Type": "application/json", }, body: JSON.stringify({ name: "@", type: "A", data: "192.0.2.1", ttl: 3600 }), }, ); const record = await res.json(); console.log("Replaced record", record.recordId); ``` ```python tab="Python" import os, requests pat = os.environ["GODADDY_PAT"] zone = "example.com" record_id = os.environ["RECORD_ID"] res = requests.put( f"https://api.godaddy.com/v3/domains/zones/{zone}/dns-records/{record_id}", json={"name": "@", "type": "A", "data": "192.0.2.1", "ttl": 3600}, headers={ "Authorization": f"Bearer {pat}", "Content-Type": "application/json", }, ) res.raise_for_status() print("Replaced record", res.json()["recordId"]) ``` ```go tab="Go" package main import ( "bytes" "encoding/json" "fmt" "net/http" "os" ) func main() { pat := os.Getenv("GODADDY_PAT") zone := "example.com" recordID := os.Getenv("RECORD_ID") body := bytes.NewReader([]byte( `{"name":"@","type":"A","data":"192.0.2.1","ttl":3600}`)) req, _ := http.NewRequest("PUT", fmt.Sprintf("https://api.godaddy.com/v3/domains/zones/%s/dns-records/%s", zone, recordID), body) req.Header.Set("Authorization", "Bearer "+pat) req.Header.Set("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() var record struct{ RecordID string `json:"recordId"` } json.NewDecoder(res.Body).Decode(&record) fmt.Println("Replaced record", record.RecordID) } ``` ```bash tab="CLI" # Replaces every record for the given type and name. Use --dry-run to preview. gddy dns set example.com --type A --name www --data 192.0.2.20 --ttl 600 ``` A successful response returns `200` with the updated `DNSRecord` in the body. GoDaddy-managed SOA and NS records cannot be replaced. Attempting to do so returns `409 Conflict`. ## Delete a record `DELETE /v3/domains/zones/{zone}/dns-records/{recordId}` permanently removes a single record from the zone. Changes are applied synchronously. The following procedure deletes a DNS record from a zone. * Delete a record: ```bash tab="curl" curl -s -X DELETE "https://api.godaddy.com/v3/domains/zones/example.com/dns-records/$RECORD_ID" \ -H "Authorization: Bearer $GODADDY_PAT" ``` ```js tab="Node" const pat = process.env.GODADDY_PAT; const zone = "example.com"; const recordId = process.env.RECORD_ID; const res = await fetch( `https://api.godaddy.com/v3/domains/zones/${zone}/dns-records/${recordId}`, { method: "DELETE", headers: { Authorization: `Bearer ${pat}` }, }, ); console.log(res.status); // expect 204 ``` ```python tab="Python" import os, requests pat = os.environ["GODADDY_PAT"] zone = "example.com" record_id = os.environ["RECORD_ID"] res = requests.delete( f"https://api.godaddy.com/v3/domains/zones/{zone}/dns-records/{record_id}", headers={"Authorization": f"Bearer {pat}"}, ) print(res.status_code) # expect 204 ``` ```go tab="Go" package main import ( "fmt" "net/http" "os" ) func main() { pat := os.Getenv("GODADDY_PAT") zone := "example.com" recordID := os.Getenv("RECORD_ID") req, _ := http.NewRequest("DELETE", fmt.Sprintf("https://api.godaddy.com/v3/domains/zones/%s/dns-records/%s", zone, recordID), nil) req.Header.Set("Authorization", "Bearer "+pat) res, _ := http.DefaultClient.Do(req) defer res.Body.Close() fmt.Println(res.StatusCode) // expect 204 } ``` ```bash tab="CLI" # Removes all records of the given type and name. Use --dry-run to preview. gddy dns delete example.com --type A --name www ``` A successful response returns `204` with no body. The API returns `404` if the `recordId` doesn't exist. Deleting an already-deleted record is not a no-op. GoDaddy-managed SOA and NS records can't be deleted; the API returns `409 Conflict` if you attempt to do so. ## Manage nameservers `PUT /v3/domains/domain-names/{domain-name}/nameservers` replaces the authoritative nameservers for a domain. Accepts a plain array of 2–13 nameserver hostnames. The GoDaddy CLI does not support nameserver management. Use the REST API for this operation. The following procedure replaces the authoritative nameservers for a domain. * Replace a nameserver for a domain: ```bash tab="curl" curl -s -X PUT "https://api.godaddy.com/v3/domains/domain-names/example.com/nameservers" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "Content-Type: application/json" \ -d '["ns1.example-dns.com", "ns2.example-dns.com"]' ``` ```js tab="Node" const pat = process.env.GODADDY_PAT; const res = await fetch( "https://api.godaddy.com/v3/domains/domain-names/example.com/nameservers", { method: "PUT", headers: { Authorization: `Bearer ${pat}`, "Content-Type": "application/json", }, body: JSON.stringify(["ns1.example-dns.com", "ns2.example-dns.com"]), }, ); console.log(res.status); // expect 202 ``` ```python tab="Python" import os, requests res = requests.put( "https://api.godaddy.com/v3/domains/domain-names/example.com/nameservers", json=["ns1.example-dns.com", "ns2.example-dns.com"], headers={ "Authorization": f"Bearer {os.environ['GODADDY_PAT']}", "Content-Type": "application/json", }, ) print(res.status_code) # expect 202 ``` ```go tab="Go" package main import ( "bytes" "fmt" "net/http" "os" ) func main() { body := bytes.NewReader([]byte(`["ns1.example-dns.com","ns2.example-dns.com"]`)) req, _ := http.NewRequest("PUT", "https://api.godaddy.com/v3/domains/domain-names/example.com/nameservers", body) req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT")) req.Header.Set("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() fmt.Println(res.StatusCode) // expect 202 } ``` A successful request returns `202 Accepted` with a `DomainOperation` in the body and a `Location` header pointing to the operation URL. Propagation to the registry is asynchronous. Poll the operation until it reaches a terminal state. Switching nameservers moves authoritative DNS off GoDaddy. Records you manage via `/v3/domains/zones/{zone}/dns-records` will no longer be served. Make sure the new nameservers are fully configured before cutting over. ## Common errors | Status | Most likely cause | | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `400` | Malformed request: missing required field, invalid field type, or unknown record type. Inspect `fields[]`. | | `401` | Authentication credentials are missing or invalid. | | `403` | Caller is not authorized. Check that your token includes the required scope (`domains.dns:update` or `domains.nameserver:update`). | | `404` | Record or domain not found, or not owned by the authenticated account. | | `409` | Conflict: request cannot be completed in the current state. Attempting to delete or replace a GoDaddy-managed SOA or NS record (`dns_record_not_mutable`). | | `422` | Valid structure but violates a business rule (for example, CNAME at apex). | | `429` | Rate limit exceeded. | Full error envelope: [Errors](https://developer.godaddy.com/docs/api-users/errors). ## DNSRecord schema | Field | Required | Description | Note | | ---------- | --------- | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- | | `recordId` | Read-only | Server-assigned stable identifier for the record. | | | `name` | Yes | Record name relative to the zone apex. | Use `@` for the apex. Wildcards (`*`) supported for A, AAAA, and CNAME. | | `type` | Yes | Record type: `A`, `AAAA`, `CNAME`, `MX`, `TXT`, `SRV`, `NS`, `CAA`, or `SOA` (SOA is read-only). | | | `data` | Yes | Record value. | Format depends on type (like IP for A/AAAA, hostname for CNAME, and text for TXT). | | `ttl` | Yes | Time-to-live in seconds. | Minimum 600 (10 min), maximum 86400 (24 hrs). | | `priority` | MX, SRV | Priority value. | Lower value equals higher preference. | | `weight` | SRV | Relative weight among equal-priority targets. | | | `port` | SRV | Target port number. | | | `service` | SRV | Service name. | Prefixed with an underscore (for example, `_http`). | | `protocol` | SRV | Transport protocol. | Prefixed with underscore (for example, `_tcp`). | | `flag` | CAA | Restriction flags byte. | Use `0` for non-critical, `128` for critical. | | `tag` | CAA | Property tag: `issue`, `issuewild`, or `iodef`. | | ## Reference * [v3 API reference](https://developer.godaddy.com/docs/references/rest/domains/v3) ## Next # How to forward a domain (https://developer.godaddy.com/en/docs/api-users/domains/manage/forwarding) --- title: How to forward a domain description: >- Create, read, update, and delete HTTP redirect rules on a domain or subdomain via the v2 forwarding API. keywords: >- 301 redirect, 302 redirect, REDIRECT_PERMANENT, REDIRECT_TEMPORARY, masked forwarding, DomainForwarding, subdomain redirect, v2 customers forwards agentNotes: permissions: - Domain Owner scopes: - 'domains.domain:read' - 'domains.domain:update' rateLimit: >- Rate-limited per credential per window. Go to /docs/api-users/rate-limits for current values. idempotent: true destructive: false failureRecovery: >- PUT is idempotent — replaying yields the same rule. DELETE is safe; a subsequent GET returns 404. Verify current state via GET before retrying ambiguous errors. related: apis: - title: Domains v2 — Forwarding href: /docs/references/rest/domains/v2/manage-domain-settings guides: - title: Manage DNS records href: /docs/api-users/domains/manage/dns - title: Registered domains href: /docs/api-users/domains/manage/list concepts: - title: Handle errors href: /docs/api-users/errors --- ## Overview Domain forwarding creates an HTTP redirect rule for a fully-qualified domain name (FQDN) — the root domain or a subdomain. When a browser requests the FQDN, the registrar returns a redirect to the target URL. Use forwarding to redirect a root domain to `www`, point a subdomain to an external URL, or set up temporary redirects during a site migration. Forwarding operations use the v2 API at `/v2/customers/{customerId}/domains/forwards/{fqdn}`. The `customerId` path parameter is a UUID (not the numeric shopper ID). Go to [Find your customer ID](#find-your-customer-id) for the lookup that returns it. Domain forwarding is v2-only. There is no equivalent in the v1 namespace. ## Prerequisites The following prerequisites are required before you manage forwarding rules: * A GoDaddy account with at least one registered domain * A [Personal Access Token](https://developer.godaddy.com/docs/api-users/auth) with `domains.domain:read` and `domains.domain:update` scopes * Your customer ID (`CUSTOMER_ID`), which the next section explains how to find ## Find your customer ID ## Find your customer ID Export the UUID as `CUSTOMER_ID` before running the examples in the following sections. ## Read a forwarding rule Returns the `DomainForwarding` object for the FQDN. Returns `404` if no forwarding rule is configured for that FQDN. The following procedure reads a forwarding rule for an FQDN. * Run the following command for your preferred language: ```bash tab="curl" curl -s "https://api.godaddy.com/v2/customers/$CUSTOMER_ID/domains/forwards/example.com" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "Accept: application/json" ``` ```js tab="Node" const pat = process.env.GODADDY_PAT; const customer = process.env.CUSTOMER_ID; const res = await fetch( `https://api.godaddy.com/v2/customers/${customer}/domains/forwards/example.com`, { headers: { Authorization: `Bearer ${pat}`, Accept: "application/json", }, }, ); if (res.status === 404) throw new Error("No forwarding rule set"); console.log(await res.json()); ``` ```python tab="Python" import os, requests customer = os.environ["CUSTOMER_ID"] res = requests.get( f"https://api.godaddy.com/v2/customers/{customer}/domains/forwards/example.com", headers={ "Authorization": f"Bearer {os.environ['GODADDY_PAT']}", "Accept": "application/json", }, ) if res.status_code == 404: print("No forwarding rule set") else: print(res.json()) ``` ```go tab="Go" package main import ( "encoding/json" "fmt" "net/http" "os" ) func main() { customer := os.Getenv("CUSTOMER_ID") url := fmt.Sprintf( "https://api.godaddy.com/v2/customers/%s/domains/forwards/example.com", customer) req, _ := http.NewRequest("GET", url, nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT")) req.Header.Set("Accept", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() if res.StatusCode == 404 { fmt.Println("No forwarding rule set") return } var rule map[string]any json.NewDecoder(res.Body).Decode(&rule) fmt.Println(rule) } ``` Response (`DomainForwarding` object): ```json { "fqdn": "example.com", "type": "REDIRECT_PERMANENT", "url": "https://www.example.com/" } ``` Returns `404` if no forwarding rule is configured for the FQDN. ## Create or replace a forwarding rule `PUT /v2/customers/{customerId}/domains/forwards/{fqdn}` creates the rule if it doesn't exist, or replaces it if it does. The call is idempotent — replaying the same request produces the same rule. The following procedure creates or replaces a forwarding rule. * Run the following command for your preferred language: ```bash tab="curl" curl -s -X PUT "https://api.godaddy.com/v2/customers/$CUSTOMER_ID/domains/forwards/example.com" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "Content-Type: application/json" \ -d '{ "fqdn": "example.com", "type": "REDIRECT_PERMANENT", "url": "https://www.example.com/" }' ``` ```js tab="Node" const pat = process.env.GODADDY_PAT; const customer = process.env.CUSTOMER_ID; const res = await fetch( `https://api.godaddy.com/v2/customers/${customer}/domains/forwards/example.com`, { method: "PUT", headers: { Authorization: `Bearer ${pat}`, "Content-Type": "application/json", }, body: JSON.stringify({ fqdn: "example.com", type: "REDIRECT_PERMANENT", url: "https://www.example.com/", }), }, ); console.log(res.status); // expect 204 ``` ```python tab="Python" import os, requests customer = os.environ["CUSTOMER_ID"] res = requests.put( f"https://api.godaddy.com/v2/customers/{customer}/domains/forwards/example.com", json={"fqdn": "example.com", "type": "REDIRECT_PERMANENT", "url": "https://www.example.com/"}, headers={ "Authorization": f"Bearer {os.environ['GODADDY_PAT']}", "Content-Type": "application/json", }, ) print(res.status_code) # expect 204 ``` ```go tab="Go" package main import ( "bytes" "fmt" "net/http" "os" ) func main() { customer := os.Getenv("CUSTOMER_ID") body := bytes.NewReader([]byte( `{"fqdn":"example.com","type":"REDIRECT_PERMANENT","url":"https://www.example.com/"}`)) req, _ := http.NewRequest("PUT", fmt.Sprintf("https://api.godaddy.com/v2/customers/%s/domains/forwards/example.com", customer), body) req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT")) req.Header.Set("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() fmt.Println(res.StatusCode) // expect 204 } ``` Returns `204 No Content` on success. ### Forward a subdomain The `fqdn` path parameter accepts any FQDN on a domain you own. The same PUT pattern applies — just change the `fqdn` path parameter and body field to the subdomain: ```bash curl -s -X PUT "https://api.godaddy.com/v2/customers/$CUSTOMER_ID/domains/forwards/shop.example.com" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "Content-Type: application/json" \ -d '{ "fqdn": "shop.example.com", "type": "REDIRECT_PERMANENT", "url": "https://store.example.com/" }' ``` ## Delete a forwarding rule Removes the forwarding rule for the FQDN. Returns `204 No Content`. After deletion, browsers visiting the FQDN no longer receive a redirect. The following procedure deletes a forwarding rule. * Run the following command for your preferred language: ```bash tab="curl" curl -s -X DELETE "https://api.godaddy.com/v2/customers/$CUSTOMER_ID/domains/forwards/example.com" \ -H "Authorization: Bearer $GODADDY_PAT" ``` ```js tab="Node" const pat = process.env.GODADDY_PAT; const customer = process.env.CUSTOMER_ID; const res = await fetch( `https://api.godaddy.com/v2/customers/${customer}/domains/forwards/example.com`, { method: "DELETE", headers: { Authorization: `Bearer ${pat}` }, }, ); console.log(res.status); // expect 204 ``` ```python tab="Python" import os, requests customer = os.environ["CUSTOMER_ID"] res = requests.delete( f"https://api.godaddy.com/v2/customers/{customer}/domains/forwards/example.com", headers={"Authorization": f"Bearer {os.environ['GODADDY_PAT']}"}, ) print(res.status_code) # expect 204 ``` ```go tab="Go" package main import ( "fmt" "net/http" "os" ) func main() { customer := os.Getenv("CUSTOMER_ID") req, _ := http.NewRequest("DELETE", fmt.Sprintf("https://api.godaddy.com/v2/customers/%s/domains/forwards/example.com", customer), nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT")) res, _ := http.DefaultClient.Do(req) defer res.Body.Close() fmt.Println(res.StatusCode) // expect 204 } ``` ## Forwarding rule fields | Field | Required | Description | | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------- | | `fqdn` | Yes | The domain or subdomain to forward (e.g. `example.com` or `shop.example.com`). Must match the `{fqdn}` path parameter. | | `type` | Yes | Redirect type — see table below. | | `url` | Yes | Destination URL (must be a valid `http://` or `https://` URL). | | `mask` | No | Masking options when `type` is `MASKED`. | ### Redirect types | Type | HTTP code | Description | | -------------------- | --------- | -------------------------------------------------------------------------------------------------------------- | | `REDIRECT_PERMANENT` | 301 | Permanent redirect. Search engines transfer link equity to the target. Use for long-term or permanent moves. | | `REDIRECT_TEMPORARY` | 302 | Temporary redirect. Search engines retain the source URL's link equity. Use for short-term redirects. | | `MASKED` | — | The browser loads the target URL but the original FQDN stays visible in the address bar. Uses an inline frame. | Masked forwarding prevents the destination URL from appearing in the browser address bar by loading it in a frame. It isn't appropriate for most use cases and can harm SEO. Prefer `REDIRECT_PERMANENT` or `REDIRECT_TEMPORARY` unless masking is specifically required. ## Common errors | Status | Most likely cause | | ------ | --------------------------------------------------------------------------------------------------------------------- | | `403` | Credential lacks write access to this domain, or `customerId` holds a numeric shopper ID instead of the account UUID. | | `404` | Domain doesn't exist, isn't owned by the authenticated account, or no forwarding rule exists (for GET/DELETE). | | `409` | Domain status prevents the operation (e.g. domain is in a pending transfer). | | `422` | Invalid `fqdn`, invalid destination URL, or unrecognized `type` value. | Full error envelope: [Errors](https://developer.godaddy.com/docs/api-users/errors). ## Reference * [v2 forwarding operations](https://developer.godaddy.com/docs/references/rest/domains/v2/manage-domain-settings) ## Next # Browse the Domains API (https://developer.godaddy.com/en/docs/api-users/domains/manage) --- title: Browse the Domains API description: 'The Domain object, related resources, and task-grouped operations.' keywords: >- DomainDetail schema, DomainDetailV2, renewAuto, locked field, nameServers, contactRegistrant, ACTIVE EXPIRED PENDING_TRANSFER, domain status values related: apis: - title: Domains v3 reference href: /docs/references/rest/domains/v3 - title: Domains v1 reference href: /docs/references/rest/domains/v1 - title: Domains v2 reference href: /docs/references/rest/domains/v2 guides: - title: Quickstart href: /docs/api-users/quickstart - title: Authenticate href: /docs/api-users/auth - title: Search domain availability href: /docs/api-users/domains/search - title: Register a domain href: /docs/api-users/domains/register --- ## Overview The Domains API supports availability search, registration, DNS and contact management, registry lock, forwarding, and inbound transfers. Operations span three version namespaces. v3 is the preferred API for domain registration, v1 and v2 provide everything else (DNS, renewals, transfers, and customer actions). ## Version namespaces The following table lists the version namespaces and what they contain. | Version | Base path | What's here | | ------- | ---------------------------------------- | ----------------------------------------------------------------------------------- | | v3 | `/v3/domains/...` | Availability checks and registration (the preferred namespace for new integrations) | | v2 | `/v2/customers/{customerId}/domains/...` | v1 capabilities with async processing and operations tracking | | v1 | `/v1/domains/...` | List, DNS, contacts, lock, and renewals | ## The Domain object A domain registered or managed through this API is the central resource of the Domains namespace. It carries registry metadata, expiration and renewal state, the four WHOIS contact roles, registry lock and privacy flags, and the authoritative nameservers returned at the TLD. Almost every operation in this namespace either returns a `DomainDetail` or modifies a field on one. The schema is named `DomainDetail` in v1 and `DomainDetailV2` in v2. The two are largely overlapping; v2 extends v1 with async operation tracking — the `DomainDetailV2` schema adds status values and action references used by long-running writes like transfers and redemptions. For single-domain detail, prefer v2: it returns more consistent status values and exposes async operation tracking if you need it. The following table lists the key fields on a `DomainDetail` object. | Field | Description | | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | | `domain` | Fully-qualified domain name (for example `example.com`). | | `status` | Current registry or registrar state, like `ACTIVE`, `PENDING_TRANSFER`, or `EXPIRED`. | | `expires` | Expiration timestamp in ISO-8601 format. | | `renewAuto` | Whether auto-renew is enabled on the domain. | | `locked` | Whether the registry transfer-lock is engaged. | | `privacy` | Whether WHOIS privacy is purchased and active. | | `nameServers` | Authoritative nameservers the registry returns for the domain. | | `contactRegistrant` / `contactAdmin` / `contactBilling` / `contactTech` | The four WHOIS contact roles, each a `Contact` object. | The full schema is in the OpenAPI specs, available as machine-readable JSON at [/openapi/domains-v1.json](https://developer.godaddy.com/openapi/domains-v1.json) and [/openapi/domains-v2.json](https://developer.godaddy.com/openapi/domains-v2.json). Go to the [Domains REST reference](https://developer.godaddy.com/docs/references/rest/domains) for the complete API reference. ### Related objects Every operation in the Domains namespace returns or accepts one of the following objects in addition to `DomainDetail`. Each links to the rendered reference where its full schema and the operations it appears on are documented. | Object | Description | Reference | | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | | `DNSRecord` | A single DNS record on a domain managed by GoDaddy's authoritative nameservers, supporting `A`, `AAAA`, `CNAME`, `MX`, `TXT`, `SRV`, `NS`, `SOA`, and `CAA` types. | [v1 DNS operations](https://developer.godaddy.com/docs/references/rest/domains/v1/record-add) | | `Contact` | A WHOIS contact record covering name, organization, address, email, and phone. The same shape is used for the registrant, admin, billing, and tech roles on a domain. | [v2 management operations](https://developer.godaddy.com/docs/references/rest/domains/v2/manage-domain-settings) | | `Action` | An asynchronous-operation tracker returned with `202 Accepted` when the API queues a long-running write (transfers, redemption). Callers poll the action endpoint until the action's `status` reaches a terminal state. | [v2 action operations](https://developer.godaddy.com/docs/references/rest/domains/v2/domain-actions) | | `DomainAvailableResponse` | The result of a single-domain availability check, including the available flag, current price in `currency-micro-unit` format, the registration period in years, and whether the answer came from a live registry call or cache. | [v1 availability operations](https://developer.godaddy.com/docs/references/rest/domains/v1/available) | | `DomainForwarding` | An HTTP forwarding rule that redirects requests for a domain to a target URL, configurable as masked or unmasked and as a permanent (`301`) or temporary (`302`) redirect. | [v2 management operations](https://developer.godaddy.com/docs/references/rest/domains/v2/manage-domain-settings) | | `DomainTransferIn` | The request shape for an inbound transfer, carrying the domain name, authcode, and required contacts. | [v2 transfer operations](https://developer.godaddy.com/docs/references/rest/domains/v2/transfer-domains) | | `Error` / `ErrorLimit` | The standard error envelope returned on `4xx` and `5xx` responses across the namespace. `ErrorLimit` extends `Error` with `retryAfterSec` for `429` rate-limited responses. | [Errors](https://developer.godaddy.com/docs/api-users/errors) | Most Domains API writes complete synchronously and return `204 No Content`. A few long-running operations — transfers, redemption — return `202 Accepted` with an `Action` body instead. Poll `GET /v2/customers/{customerId}/domains/actions/{actionId}` until `status` reaches a terminal state (`COMPLETED`, `FAILED`, or `CANCELLED`). ## Tasks ### Manage existing domains ### Acquire new domains * [Generate a Personal Access Token (PAT)](https://developer.godaddy.com/docs/api-users/auth/how-to). * [Fund your account](https://www.godaddy.com/help/add-a-payment-method-to-my-godaddy-account-20037) for write operations. * [Set up the CLI](https://developer.godaddy.com/docs/api-users/cli/set-up). * [Make your first call](https://developer.godaddy.com/docs/api-users/quickstart). # How to list registered domains (https://developer.godaddy.com/en/docs/api-users/domains/manage/list) --- title: How to list registered domains description: >- Retrieve the domains owned by the authenticated account, with cursor pagination, and fetch full detail for any one domain. keywords: >- GET /v3/domains/domain-names, GET /v1/domains, pageToken, lifecycleGroups, REGISTERED status, domain inventory, DomainCollection, list all domains. agentNotes: permissions: - DNS Management - Domain Owner scopes: - 'domains.domain:read' rateLimit: >- Rate-limited per credential per window. Go to /docs/api-users/rate-limits for current values. idempotent: true destructive: false failureRecovery: >- Read-only. Safe to retry any failure. For paginated cursors, resume from the last successful marker. related: apis: - title: 'Domains v3: Domain names' href: /docs/references/rest/domains/v3/list-domains - title: 'Domains v1: List domains' href: /docs/references/rest/domains/v1/list - title: 'Domains v2: Get domain detail' href: /docs/references/rest/domains/v2/manage-domain-settings guides: - title: Update contacts href: /docs/api-users/domains/manage/update-contacts - title: Manage renewals href: /docs/api-users/domains/manage/renewals - title: Manage DNS records href: /docs/api-users/domains/manage/dns concepts: - title: Pagination href: /docs/api-users/pagination - title: Authentication href: /docs/api-users/auth --- ## Overview List domains registered to an account using `GET /v3/domains/domain-names` (recommended) or the legacy `GET /v1/domains`. Fetch full detail for any single domain using `GET /v2/customers/{customerId}/domains/{domain}`. v3 uses cursor-based HATEOAS pagination; v1 uses `limit` and `marker`. ## v3: List registered domains `GET /v3/domains/domain-names` returns a paginated list of domains owned by the authenticated account. Results use cursor-based pagination via HATEOAS links in the response. The following procedure lists registered domains using the v3 API. * Run the following command for your preferred language: ```bash tab="curl" curl -s "https://api.godaddy.com/v3/domains/domain-names" \ -H "Authorization: Bearer $GODADDY_PAT" ``` ```js tab="Node" const pat = process.env.GODADDY_PAT; const res = await fetch("https://api.godaddy.com/v3/domains/domain-names", { headers: { Authorization: `Bearer ${pat}` }, }); const { items, links } = await res.json(); console.log(items.map((d) => d.domain)); ``` ```python tab="Python" import os, requests pat = os.environ["GODADDY_PAT"] res = requests.get( "https://api.godaddy.com/v3/domains/domain-names", headers={"Authorization": f"Bearer {pat}"}, ) res.raise_for_status() for d in res.json()["items"]: print(d["domain"], d.get("status")) ``` ```go tab="Go" package main import ( "encoding/json" "fmt" "net/http" "os" ) func main() { pat := os.Getenv("GODADDY_PAT") req, _ := http.NewRequest("GET", "https://api.godaddy.com/v3/domains/domain-names", nil) req.Header.Set("Authorization", "Bearer "+pat) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() var body struct { Items []struct { Domain string `json:"domain"` Status string `json:"status"` } `json:"items"` Links []struct { Rel string `json:"rel"` Href string `json:"href"` } `json:"links"` } json.NewDecoder(res.Body).Decode(&body) for _, d := range body.Items { fmt.Println(d.Domain, d.Status) } } ``` ```bash tab="CLI" gddy domain list # Filter by status: gddy domain list --status ACTIVE ``` The response is a `DomainCollection` with `items` (the current page) and `links` (pagination navigation): ```json { "items": [ { "domain": "example.com", "status": "ACTIVE", "expiresAt": "2027-01-15T00:00:00Z", "autoRenew": true, "privacy": false, "transferLock": true, "nameServers": ["ns01.domaincontrol.com", "ns02.domaincontrol.com"] } ], "links": [ { "rel": "self", "href": "/v3/domains/domain-names?pageSize=25" }, { "rel": "next", "href": "/v3/domains/domain-names?pageSize=25&pageToken=eyJkb21haW4iOiJleGFtcGxlLmNvbSJ9" } ] } ``` Follow the `rel=next` link to retrieve the next page. When `rel=next` is absent, you have reached the last page. ### Filtering by lifecycle group Use the `lifecycleGroups` query parameter to filter results by `DomainLifecycleGroup`: | Value | Includes | | ------------------ | ------------------------------------------------------------------------------------------------------ | | `PENDING` | Domains with setup in progress (for example, `PENDING_REGISTRATION`). | | `REGISTERED` | Active, operational domains (for example, `ACTIVE`, `PARKED`). | | `PENDING_TERMINAL` | Domains approaching a terminal state (for example, `PENDING_TRANSFER`, `EXPIRED`). | | `TERMINAL` | Domains that are no longer manageable (for example, `CANCELLED`, `DELETED_REDEEMABLE`, `TRANSFERRED`). | ```bash curl -s "https://api.godaddy.com/v3/domains/domain-names?lifecycleGroups=REGISTERED" \ -H "Authorization: Bearer $GODADDY_PAT" ``` Reference: [`GET /v3/domains/domain-names`](https://developer.godaddy.com/docs/references/rest/domains/v3/list-domains) ## v1 — List registered domains `GET /v1/domains` returns the domains owned by the authenticated account, paginated with `limit` and `marker`. `GET /v1/domains/{domain}` returns full detail for a single domain. This page assumes you have a PAT credential. Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) and [Quickstart](https://developer.godaddy.com/docs/api-users/quickstart) if you don't. ## Retrieve registered domains The response is an array of domain summaries. For pagination semantics and a looping example, go to [Pagination](https://developer.godaddy.com/docs/api-users/pagination). The following procedure retrieves the domains registered to the authenticated account. * Run the following command for your preferred language: ```bash tab="curl" curl -s "https://api.godaddy.com/v1/domains?limit=100" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "Accept: application/json" ``` ```js tab="Node" const pat = process.env.GODADDY_PAT; const res = await fetch("https://api.godaddy.com/v1/domains?limit=100", { headers: { Authorization: `Bearer ${pat}`, Accept: "application/json", }, }); const domains = await res.json(); console.log(domains.map((d) => d.domain)); ``` ```python tab="Python" import os, requests pat = os.environ["GODADDY_PAT"] res = requests.get( "https://api.godaddy.com/v1/domains", params={"limit": 100}, headers={ "Authorization": f"Bearer {pat}", "Accept": "application/json", }, ) res.raise_for_status() for d in res.json(): print(d["domain"], d.get("status")) ``` ```go tab="Go" package main import ( "encoding/json" "fmt" "net/http" "os" ) type Domain struct { Domain string `json:"domain"` Status string `json:"status"` } func main() { pat := os.Getenv("GODADDY_PAT") req, _ := http.NewRequest("GET", "https://api.godaddy.com/v1/domains?limit=100", nil) req.Header.Set("Authorization", "Bearer "+pat) req.Header.Set("Accept", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() var domains []Domain json.NewDecoder(res.Body).Decode(&domains) for _, d := range domains { fmt.Println(d.Domain, d.Status) } } ``` ### Filtering `GET /v1/domains` accepts these query parameters in addition to `limit` and `marker`: | Parameter | Notes | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `statuses` | Comma-separated list of domain statuses (e.g. `ACTIVE`, `EXPIRED`, `PENDING_TRANSFER`). Returns only domains in one of the listed statuses. | | `statusGroups` | Coarser filter — by status group (e.g. `VISIBLE`, `EXPIRED`). | | `includes` | Comma-separated list of expansions to include (e.g. `contacts`). Adds related objects to each item without a follow-up call. | | `modifiedDate` | ISO-8601 timestamp. Returns only domains modified at or after this time. | Reference: [`GET /v1/domains`](https://developer.godaddy.com/docs/references/rest/domains/v1/list). ## Get details for a single domain The response is a `DomainDetail` object covering registration metadata, expiration, contacts, nameservers, lock state, privacy state, and auto-renew configuration. For the full schema, see the reference. The following procedure retrieves details for a single domain. * Run the following command for your preferred language: ```bash tab="curl" curl -s "https://api.godaddy.com/v1/domains/example.com" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "Accept: application/json" ``` ```js tab="Node" const pat = process.env.GODADDY_PAT; const res = await fetch("https://api.godaddy.com/v1/domains/example.com", { headers: { Authorization: `Bearer ${pat}`, Accept: "application/json", }, }); const detail = await res.json(); console.log(detail.domain, detail.status, detail.expires); ``` ```python tab="Python" import os, requests pat = os.environ["GODADDY_PAT"] res = requests.get( "https://api.godaddy.com/v1/domains/example.com", headers={"Authorization": f"Bearer {pat}", "Accept": "application/json"}, ) res.raise_for_status() d = res.json() print(d["domain"], d["status"], d["expires"]) ``` ```go tab="Go" package main import ( "encoding/json" "fmt" "net/http" "os" ) func main() { pat := os.Getenv("GODADDY_PAT") req, _ := http.NewRequest("GET", "https://api.godaddy.com/v1/domains/example.com", nil) req.Header.Set("Authorization", "Bearer "+pat) req.Header.Set("Accept", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() var detail struct { Domain string `json:"domain"` Status string `json:"status"` Expires string `json:"expires"` } json.NewDecoder(res.Body).Decode(&detail) fmt.Println(detail.Domain, detail.Status, detail.Expires) } ``` ```bash tab="CLI" gddy domain get example.com ``` Reference: [`GET /v1/domains/{domain}`](https://developer.godaddy.com/docs/references/rest/domains/v1/get). ## v2 — single domain detail Use the v2 endpoint for single-domain detail. It returns consistent status values and gives you access to async operation tracking if you need it. The following procedure retrieves domain details for a specific customer. * Run the following command for your preferred language: ```bash tab="curl" curl -s "https://api.godaddy.com/v2/customers/$CUSTOMER_ID/domains/example.com" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "Accept: application/json" ``` ```js tab="Node" const pat = process.env.GODADDY_PAT; const customer = process.env.CUSTOMER_ID; const res = await fetch( `https://api.godaddy.com/v2/customers/${customer}/domains/example.com`, { headers: { Authorization: `Bearer ${pat}`, Accept: "application/json", }, }, ); const detail = await res.json(); console.log(detail.domain, detail.status); ``` ```python tab="Python" import os, requests customer = os.environ["CUSTOMER_ID"] res = requests.get( f"https://api.godaddy.com/v2/customers/{customer}/domains/example.com", headers={ "Authorization": f"Bearer {os.environ['GODADDY_PAT']}", "Accept": "application/json", }, ) res.raise_for_status() d = res.json() print(d["domain"], d["status"]) ``` ```go tab="Go" package main import ( "encoding/json" "fmt" "net/http" "os" ) func main() { customer := os.Getenv("CUSTOMER_ID") pat := os.Getenv("GODADDY_PAT") req, _ := http.NewRequest("GET", fmt.Sprintf("https://api.godaddy.com/v2/customers/%s/domains/example.com", customer), nil) req.Header.Set("Authorization", "Bearer "+pat) req.Header.Set("Accept", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() var detail struct { Domain string `json:"domain"` Status string `json:"status"` } json.NewDecoder(res.Body).Decode(&detail) fmt.Println(detail.Domain, detail.Status) } ``` Reference: [`GET /v2/customers/{customerId}/domains/{domain}`](https://developer.godaddy.com/docs/references/rest/domains/v2/manage-domain-settings). v2 paths (`/v2/customers/{customerId}/domains/...`) are preferred for single-domain detail; v1 paths are appropriate for list operations and account-scoped writes. ## Common errors | Status | Most likely cause | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | `401` | Token missing, expired, or revoked. | | `403` | Account doesn't meet requirements for this operation. Go to [Account requirements](https://developer.godaddy.com/docs/api-users/auth#account-requirements). | | `404` (single-domain GET) | Domain doesn't exist, or isn't owned by the authenticated account. | | `429` | Rate limit. Wait `retryAfterSec` and retry. | Full error envelope and retry guidance: [Errors](https://developer.godaddy.com/docs/api-users/errors). ## Next # How to lock a domain (https://developer.godaddy.com/en/docs/api-users/domains/manage/lock) --- title: How to lock a domain description: >- Read and toggle the registry transfer-lock state on a domain you own. Unlock only when a transfer or registrant change requires it. keywords: >- EPP lock, clientTransferProhibited, domain theft prevention, transfer protection, registrar lock, PATCH domains, locked:true locked:false agentNotes: permissions: - Domain Owner scopes: - 'domains.domain:read' - 'domains.domain:update' rateLimit: >- Rate-limited per credential per window. Go to /docs/api-users/rate-limits for current values. idempotent: true destructive: false failureRecovery: >- Idempotent — locking an already-locked domain is a no-op. Prefer GET-before-PATCH to confirm current state on error retries. related: apis: - title: Domains v1 — Update domain href: /docs/references/rest/domains/v1/update guides: - title: Update contacts href: /docs/api-users/domains/manage/update-contacts concepts: - title: Handle errors href: /docs/api-users/errors --- ## Overview Registry lock sets the `clientTransferProhibited` flag at the domain registry, preventing any registrar from initiating an outbound transfer without your explicit consent. Lock is enabled by default at registration and has no effect on DNS resolution, email delivery, or any service hosted on the domain. Disable it only for the duration of a transfer or registrant change, then re-enable it immediately. Lock state is a field on the `DomainDetail` object, read with `GET /v1/domains/{domain}` and toggled with `PATCH /v1/domains/{domain}`. Registry lock management isn't available in v3 yet. This page uses the v1 endpoint (`PATCH /v1/domains/{domain}`). ## Prerequisites The following prerequisites are required before you manage registry lock: * A GoDaddy account that owns the domain * A [Personal Access Token](https://developer.godaddy.com/docs/api-users/auth) with `domains.domain:read` and `domains.domain:update` scopes ## Read lock state Returns the full `DomainDetail` object. The `locked` boolean is `true` when `clientTransferProhibited` is set at the registry. The following procedure reads the lock state for a domain. * Run the following command: ```bash curl -s "https://api.godaddy.com/v1/domains/example.com" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "Accept: application/json" ``` ```json { "domain": "example.com", "status": "ACTIVE", "locked": true, "renewAuto": true, "expires": "2026-03-15T00:00:00.000Z" } ``` ## Enable lock Send `{"locked": true}` to the domain update endpoint. Returns `204 No Content`. Idempotent — locking an already-locked domain is a no-op. The following procedure enables the registry transfer-lock on a domain. * Run the following command for your preferred language: ```bash tab="curl" curl -s -X PATCH "https://api.godaddy.com/v1/domains/example.com" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "Content-Type: application/json" \ -d '{"locked": true}' ``` ```js tab="Node" const pat = process.env.GODADDY_PAT; const res = await fetch("https://api.godaddy.com/v1/domains/example.com", { method: "PATCH", headers: { Authorization: `Bearer ${pat}`, "Content-Type": "application/json", }, body: JSON.stringify({ locked: true }), }); console.log(res.status); // expect 204 ``` ```python tab="Python" import os, requests res = requests.patch( "https://api.godaddy.com/v1/domains/example.com", json={"locked": True}, headers={ "Authorization": f"Bearer {os.environ['GODADDY_PAT']}", "Content-Type": "application/json", }, ) print(res.status_code) # expect 204 ``` ```go tab="Go" package main import ( "bytes" "fmt" "net/http" "os" ) func main() { body := bytes.NewReader([]byte(`{"locked": true}`)) req, _ := http.NewRequest("PATCH", "https://api.godaddy.com/v1/domains/example.com", body) req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT")) req.Header.Set("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() fmt.Println(res.StatusCode) // expect 204 } ``` ## Disable lock Send `{"locked": false}` to release the transfer-lock. Returns `204 No Content`. The following procedure disables the registry transfer-lock on a domain. Unlock only for as long as the transfer or registrant change requires. After the operation completes, re-enable lock with `{"locked": true}`. High-value and production-serving domains should be locked at all other times. * Run the following command for your preferred language: ```bash tab="curl" curl -s -X PATCH "https://api.godaddy.com/v1/domains/example.com" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "Content-Type: application/json" \ -d '{"locked": false}' ``` ```js tab="Node" const pat = process.env.GODADDY_PAT; const res = await fetch("https://api.godaddy.com/v1/domains/example.com", { method: "PATCH", headers: { Authorization: `Bearer ${pat}`, "Content-Type": "application/json", }, body: JSON.stringify({ locked: false }), }); console.log(res.status); // expect 204 ``` ```python tab="Python" import os, requests res = requests.patch( "https://api.godaddy.com/v1/domains/example.com", json={"locked": False}, headers={ "Authorization": f"Bearer {os.environ['GODADDY_PAT']}", "Content-Type": "application/json", }, ) print(res.status_code) # expect 204 ``` ```go tab="Go" package main import ( "bytes" "fmt" "net/http" "os" ) func main() { body := bytes.NewReader([]byte(`{"locked": false}`)) req, _ := http.NewRequest("PATCH", "https://api.godaddy.com/v1/domains/example.com", body) req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT")) req.Header.Set("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() fmt.Println(res.StatusCode) // expect 204 } ``` ## When to unlock Two operations require the lock to be off before they can proceed: | Scenario | Detail | | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | **Outbound transfer** | The receiving registrar cannot initiate the transfer until lock is disabled. | | **Registrant change on some TLDs** | A subset of ccTLDs require unlock before the registry accepts a registrant update. Check the TLD's registry policy before attempting the change. | Lock is enabled by default at registration. Leave it on at all other times — it has no effect on DNS resolution, email delivery, or any service hosted on the domain. ## Request body `PATCH /v1/domains/{domain}` accepts a `DomainUpdate` object. Only the fields you include are updated. | Field | Type | Description | | ------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------- | | `locked` | boolean | Whether to engage the registry transfer-lock. | | `renewAuto` | boolean | Whether auto-renew is enabled. Go to [Renewals](https://developer.godaddy.com/docs/api-users/domains/manage/renewals). | | `nameServers` | string\[] | Authoritative nameservers (apex). Go to [DNS → Manage nameservers](https://developer.godaddy.com/docs/api-users/domains/manage/dns#manage-nameservers-v2). | | `exposeWhois` | boolean | Whether contact details appear in WHOIS. Overridden by `privacy`. | ## Common errors | Status | Most likely cause | | ------ | ----------------------------------------------------------------- | | `400` | Malformed request body. | | `403` | Credential lacks write access to this domain. | | `404` | Domain doesn't exist or isn't owned by the authenticated account. | | `409` | Conflicting operation in progress (e.g. mid-transfer). | | `422` | Invalid field value. | Full error envelope: [Errors](https://developer.godaddy.com/docs/api-users/errors). ## Reference * [v1 domain settings — domain update (`PATCH /v1/domains/{domain}`)](https://developer.godaddy.com/docs/references/rest/domains/v1/update) ## Next # How to manage renewals (https://developer.godaddy.com/en/docs/api-users/domains/manage/renewals) --- title: How to manage renewals description: Toggle auto-renew and manually renew a domain before expiration. keywords: >- renewAuto field, POST renew, renewal period, orderId, grace period, Redemption period, PATCH renewAuto, domain expiry, currency-micro-unit. agentNotes: permissions: - Domain Owner - Billing scopes: - 'domains.domain:read' - 'domains.domain:update' rateLimit: >- Rate-limited per credential per window. Go to /docs/api-users/rate-limits for current values. idempotent: false destructive: false failureRecovery: >- renewAuto toggle is idempotent. Manual renew is NOT; charging the account is a real-money side effect. On timeout or network error, GET the domain to verify the new expires timestamp before retrying. related: apis: - title: 'Domains v1: Renew' href: /docs/references/rest/domains/v1/renew guides: - title: Registered domains href: /docs/api-users/domains/manage/list - title: Update contacts href: /docs/api-users/domains/manage/update-contacts concepts: - title: Handle errors href: /docs/api-users/errors --- ## Overview Control when and how a domain renews using two mechanisms: auto-renew (a flag that fires before expiration) and manual renewal (a POST call that extends registration and charges the account). Use auto-renew for domains you want to keep without manual intervention; use manual renewal to extend a domain ahead of an upcoming expiration. Renewal management isn't available in v3 yet. This page uses the v1 endpoints (`POST /v1/domains/{domain}/renew` and `PATCH /v1/domains/{domain}`). A domain's renewal state is controlled through two mechanisms: * **Auto-renew**: a flag on the domain that tells the registrar to renew automatically before expiration. Free to toggle. No registry interaction until the renewal actually fires. * **Manual renew**: a `POST /v1/domains/{domain}/renew` call that adds a registration period immediately. Charges the account in production. Both the `renewAuto` flag and the `expires` timestamp live on the `DomainDetail` object. ## Read renewal state Returns the full `DomainDetail` object. The `renewAuto` flag and `expires` timestamp are the two renewal-relevant fields. The following procedure reads the renewal state for a domain. * Run the following command: ```bash curl -s "https://api.godaddy.com/v1/domains/example.com" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "Accept: application/json" ``` ```json { "domain": "example.com", "status": "ACTIVE", "renewAuto": true, "expires": "2026-03-15T00:00:00.000Z" } ``` ## Toggle auto-renew Auto-renew is toggled through `PATCH /v1/domains/{domain}`. The following procedure toggles auto-renew on a domain. **Enable auto-renew:** * Run the following command for your preferred language: ```bash tab="curl" curl -s -X PATCH "https://api.godaddy.com/v1/domains/example.com" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "Content-Type: application/json" \ -d '{"renewAuto": true}' ``` ```js tab="Node" const pat = process.env.GODADDY_PAT; const res = await fetch("https://api.godaddy.com/v1/domains/example.com", { method: "PATCH", headers: { Authorization: `Bearer ${pat}`, "Content-Type": "application/json", }, body: JSON.stringify({ renewAuto: true }), }); console.log(res.status); // expect 204 ``` ```python tab="Python" import os, requests res = requests.patch( "https://api.godaddy.com/v1/domains/example.com", json={"renewAuto": True}, headers={ "Authorization": f"Bearer {os.environ['GODADDY_PAT']}", "Content-Type": "application/json", }, ) print(res.status_code) # expect 204 ``` ```go tab="Go" package main import ( "bytes" "fmt" "net/http" "os" ) func main() { body := bytes.NewReader([]byte(`{"renewAuto": true}`)) req, _ := http.NewRequest("PATCH", "https://api.godaddy.com/v1/domains/example.com", body) req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT")) req.Header.Set("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() fmt.Println(res.StatusCode) // expect 204 } ``` **Disable auto-renew:** * Run the following command: ```bash curl -s -X PATCH "https://api.godaddy.com/v1/domains/example.com" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "Content-Type: application/json" \ -d '{"renewAuto": false}' ``` Both return `204 No Content`. The operation is free and idempotent. Setting the flag to its current value is a no-op. Auto-renew is enabled by default at registration time. If you are managing domains on behalf of customers, consider whether you want the domain to auto-renew without explicit confirmation. ## Manually renew a domain `POST /v1/domains/{domain}/renew` appends a registration period to the current expiration date. The following procedure manually renews a domain. * Run the following command for your preferred language: ```bash tab="curl" curl -s -X POST "https://api.godaddy.com/v1/domains/example.com/renew" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "Content-Type: application/json" \ -d '{"period": 1}' ``` ```js tab="Node" const pat = process.env.GODADDY_PAT; const res = await fetch("https://api.godaddy.com/v1/domains/example.com/renew", { method: "POST", headers: { Authorization: `Bearer ${pat}`, "Content-Type": "application/json", }, body: JSON.stringify({ period: 1 }), }); if (!res.ok) throw new Error(`Renewal failed: ${res.status}`); const order = await res.json(); console.log("Order:", order.orderId, "Total:", order.total / 1_000_000, order.currency); ``` ```python tab="Python" import os, requests res = requests.post( "https://api.godaddy.com/v1/domains/example.com/renew", json={"period": 1}, headers={ "Authorization": f"Bearer {os.environ['GODADDY_PAT']}", "Content-Type": "application/json", }, ) res.raise_for_status() order = res.json() print("Order:", order["orderId"], "Total:", order["total"] / 1_000_000, order["currency"]) ``` ```go tab="Go" package main import ( "bytes" "encoding/json" "fmt" "net/http" "os" ) func main() { body := bytes.NewReader([]byte(`{"period": 1}`)) req, _ := http.NewRequest("POST", "https://api.godaddy.com/v1/domains/example.com/renew", body) req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT")) req.Header.Set("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() var order struct { OrderID int `json:"orderId"` Total int `json:"total"` Currency string `json:"currency"` } json.NewDecoder(res.Body).Decode(&order) fmt.Printf("Order: %d Total: %.2f %s\n", order.OrderID, float64(order.Total)/1_000_000, order.Currency) } ``` Response: ```json { "orderId": 8675309, "itemCount": 1, "total": 11990000, "currency": "USD" } ``` `total` is in `currency-micro-unit` format. Divide by 1,000,000 to get the value in `currency`. ### Request body | Field | Required | Description | | -------- | -------- | ------------------------------------------------------------------------------- | | `period` | No | Years to add (1–10). Defaults to the period specified at original registration. | `POST /v1/domains/{domain}/renew` charges the account's billing method. Verify the domain name, period, and price before sending. To check the renewal price first, call the v2 domain detail endpoint: ```bash curl -s "https://api.godaddy.com/v2/customers/{customerId}/domains/example.com" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "Content-Type: application/json" ``` The response includes a `renewal` object with the current price: ```json { "renewal": { "currency": "USD", "price": 11990000, "renewable": true } } ``` `price` is in `currency-micro-unit` format. Divide by 1,000,000 for the currency value (for example, `11990000` = `$11.99`). ### Response: DomainPurchaseResponse | Field | Description | | ----------- | --------------------------------------------------------------------------------------- | | `orderId` | Unique identifier of the order. | | `itemCount` | Number of items in the order (typically 1). | | `total` | Total cost in `currency-micro-unit` format. Divide by 1,000,000 for the currency value. | | `currency` | ISO 4217 currency code (for example, `USD`). | ## Expiration and grace periods After a domain expires, GoDaddy provides a recovery window before the domain is permanently released. Standard renewal pricing applies for approximately 12 days post-expiration. After that, the domain leaves your account and additional fees apply to recover it. ccTLDs and some other TLDs follow different expiration timelines. Check the full timeline before relying on these windows in your logic. Go to [Standard domain expiration timeline](https://www.godaddy.com/help/standard-domain-expiration-timeline-609) for the complete day-by-day expiration timeline. ## Common errors | Status | Most likely cause | | ------ | ---------------------------------------------------------------------------------------- | | `400` | Malformed request body or invalid `period` value. | | `403` | Credential lacks write access to this domain. | | `404` | Domain doesn't exist or isn't owned by the authenticated account. | | `409` | Domain status prevents renewal (for example, a domain in a transfer). | | `422` | Period exceeds the TLD maximum or would push total registration past the registry limit. | Full error envelope: [Errors](https://developer.godaddy.com/docs/api-users/errors). ## Reference * [v1 domain settings — `PATCH /v1/domains/{domain}` (auto-renew toggle)](https://developer.godaddy.com/docs/references/rest/domains/v1/update) * [v1 registration and renewals — `POST /v1/domains/{domain}/renew`](https://developer.godaddy.com/docs/references/rest/domains/v1/renew) ## Next # How to update contacts (https://developer.godaddy.com/en/docs/api-users/domains/manage/update-contacts) --- title: How to update contacts description: >- Change the registrant, admin, billing, or tech contact on a domain you own via PATCH /v1/domains/{domain}/contacts. keywords: >- WHOIS contact update, E.164 phone format, nameFirst nameLast, DomainContacts, changeOfRegistrant, ICANN approval, registrant email change, contact object agentNotes: permissions: - Domain Owner scopes: - 'domains.domain:update' rateLimit: >- Rate-limited per credential per window. Go to /docs/api-users/rate-limits for current values. idempotent: true destructive: false failureRecovery: >- Idempotent on identical bodies. On 409 (registrant change on locked ccTLD), unlock, retry, and relock. If the ICANN approval flow was triggered (privacy off and a registrant identity field changed), the update is pending old-registrant approval — use DELETE /v2/customers/{customerId}/domains/{domain}/changeOfRegistrant to cancel. Verify state via GET before retrying an unclear failure. related: apis: - title: Domains v1 — Update contacts href: /docs/references/rest/domains/v1/update-contacts guides: - title: Lock a domain href: /docs/api-users/domains/manage/lock - title: Registered domains href: /docs/api-users/domains/manage/list concepts: - title: Handle errors href: /docs/api-users/errors - title: Authentication href: /docs/api-users/auth - title: Domain management concepts href: /docs/api-users/domains/concepts --- ## Overview Update the registrant, admin, billing, or tech contact on a domain you own using `PATCH /v1/domains/{domain}/contacts`. Each contact role can be updated independently — include only the roles you want to change in the request body. The registrant contact is the legal owner of the domain and is required; the other three roles default to the registrant if omitted. ## Prerequisites The following prerequisites are required before you update domain contacts: * A GoDaddy account that owns the domain * A [Personal Access Token](https://developer.godaddy.com/docs/api-users/auth) with `domains.domain:update` scope * Registrant name, email, phone (E.164 format), and mailing address ## Update the registrant contact Send a `PATCH` with only `contactRegistrant` in the body. Admin, billing, and tech contacts are untouched when omitted. Returns `204 No Content`. The following procedure updates the registrant contact for a domain. A subset of ccTLDs require registry lock to be disabled before the registry accepts a registrant update. If you receive a `409`, check whether the domain is locked and disable it before retrying. Re-enable lock after the update completes. Go to [Registry lock](https://developer.godaddy.com/docs/api-users/domains/manage/lock). * Run the following command for your preferred language: ```bash tab="curl" curl -s -X PATCH "https://api.godaddy.com/v1/domains/example.com/contacts" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "Content-Type: application/json" \ -d '{ "contactRegistrant": { "nameFirst": "Jane", "nameLast": "Smith", "email": "jane@example.com", "phone": "+1.5555550100", "addressMailing": { "address1": "123 Main St", "city": "Tempe", "state": "AZ", "postalCode": "85281", "country": "US" } } }' ``` ```js tab="Node" const pat = process.env.GODADDY_PAT; const body = { contactRegistrant: { nameFirst: "Jane", nameLast: "Smith", email: "jane@example.com", phone: "+1.5555550100", addressMailing: { address1: "123 Main St", city: "Tempe", state: "AZ", postalCode: "85281", country: "US", }, }, }; const res = await fetch("https://api.godaddy.com/v1/domains/example.com/contacts", { method: "PATCH", headers: { Authorization: `Bearer ${pat}`, "Content-Type": "application/json", }, body: JSON.stringify(body), }); console.log(res.status); // expect 204 ``` ```python tab="Python" import os, requests pat = os.environ["GODADDY_PAT"] body = { "contactRegistrant": { "nameFirst": "Jane", "nameLast": "Smith", "email": "jane@example.com", "phone": "+1.5555550100", "addressMailing": { "address1": "123 Main St", "city": "Tempe", "state": "AZ", "postalCode": "85281", "country": "US", }, } } res = requests.patch( "https://api.godaddy.com/v1/domains/example.com/contacts", json=body, headers={ "Authorization": f"Bearer {pat}", "Content-Type": "application/json", }, ) print(res.status_code) # expect 204 ``` ```go tab="Go" package main import ( "bytes" "encoding/json" "fmt" "net/http" "os" ) func main() { pat := os.Getenv("GODADDY_PAT") body := map[string]any{ "contactRegistrant": map[string]any{ "nameFirst": "Jane", "nameLast": "Smith", "email": "jane@example.com", "phone": "+1.5555550100", "addressMailing": map[string]any{ "address1": "123 Main St", "city": "Tempe", "state": "AZ", "postalCode": "85281", "country": "US", }, }, } b, _ := json.Marshal(body) req, _ := http.NewRequest("PATCH", "https://api.godaddy.com/v1/domains/example.com/contacts", bytes.NewReader(b)) req.Header.Set("Authorization", "Bearer "+pat) req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() fmt.Println(res.StatusCode) // expect 204 } ``` Returns `204 No Content` on success. ## ICANN registrant contact change approval Changing identifying registrant fields while WHOIS privacy is disabled triggers the ICANN Contact Change Approval flow. Go to [ICANN registrant contact change approval](https://developer.godaddy.com/docs/api-users/domains/concepts#icann-registrant-contact-change-approval) for details on when this applies. ### Check a pending change Use the v2 GET endpoint to confirm whether an approval is pending before taking action. The following procedure checks whether a pending ICANN contact change approval is in progress. * Run the following command: ```bash curl -s "https://api.godaddy.com/v2/customers/{customerId}/domains/{domain}/changeOfRegistrant" \ -H "Authorization: Bearer $GODADDY_PAT" ``` ### Cancel a pending change Canceling the request reverts the registrant contact to its previous values. The following procedure cancels a pending ICANN contact change approval. * Run the following command: ```bash curl -s -X DELETE \ "https://api.godaddy.com/v2/customers/{customerId}/domains/{domain}/changeOfRegistrant" \ -H "Authorization: Bearer $GODADDY_PAT" ``` Returns `204 No Content` on success. ## Update all four roles at once Include all four roles in one call. Each uses the same `Contact` shape. The following procedure updates all four contact roles in a single request. * Run the following command: ```bash curl -s -X PATCH "https://api.godaddy.com/v1/domains/example.com/contacts" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "Content-Type: application/json" \ -d '{ "contactRegistrant": { "nameFirst": "Jane", "nameLast": "Smith", "email": "jane@example.com", "phone": "+1.5555550100", "addressMailing": { "address1": "123 Main St", "city": "Tempe", "state": "AZ", "postalCode": "85281", "country": "US" } }, "contactAdmin": { "nameFirst": "Jane", "nameLast": "Smith", "email": "jane@example.com", "phone": "+1.5555550100", "addressMailing": { "address1": "123 Main St", "city": "Tempe", "state": "AZ", "postalCode": "85281", "country": "US" } }, "contactBilling": { "nameFirst": "Jane", "nameLast": "Smith", "email": "jane@example.com", "phone": "+1.5555550100", "addressMailing": { "address1": "123 Main St", "city": "Tempe", "state": "AZ", "postalCode": "85281", "country": "US" } }, "contactTech": { "nameFirst": "Jane", "nameLast": "Smith", "email": "jane@example.com", "phone": "+1.5555550100", "addressMailing": { "address1": "123 Main St", "city": "Tempe", "state": "AZ", "postalCode": "85281", "country": "US" } } }' ``` ## Contact object | Field | Required | Description | | ---------------- | -------- | --------------------------------------- | | `nameFirst` | Yes | First name. | | `nameLast` | Yes | Last name. | | `email` | Yes | Email address. | | `phone` | Yes | Phone in E.164 format: `+1.5555550100`. | | `addressMailing` | Yes | Mailing address object — see below. | | `nameMiddle` | No | Middle name. | | `organization` | No | Organization name. | | `jobTitle` | No | Job title. | | `fax` | No | Fax number in E.164 format. | ### Mailing address | Field | Required | Description | | ------------ | -------- | ------------------------------------------------------------------- | | `address1` | Yes | Street address line 1. | | `address2` | No | Street address line 2. | | `city` | Yes | City. | | `state` | Yes | State or province code (for countries that use it). | | `postalCode` | Yes | Postal code. | | `country` | Yes | Two-letter ISO 3166-1 alpha-2 country code (e.g. `US`, `GB`, `DE`). | ## Request body summary `PATCH /v1/domains/{domain}/contacts` accepts a `DomainContacts` object. | Role | Required | Description | | ------------------- | -------- | ------------------------------------------------ | | `contactRegistrant` | Yes | The legal owner of the domain. | | `contactAdmin` | No | Administrative contact. Not modified if omitted. | | `contactBilling` | No | Billing contact. Not modified if omitted. | | `contactTech` | No | Technical contact. Not modified if omitted. | ## Common errors | Status | Most likely cause | | ------ | ----------------------------------------------------------------------------------------------------------------------------------- | | `400` | Malformed request body or invalid contact field (bad email format, invalid country code). Inspect `fields[]` in the error response. | | `403` | Credential lacks write access to this domain. | | `404` | Domain doesn't exist or isn't owned by the authenticated account. | | `409` | Domain is locked and the TLD requires unlock for registrant changes. | | `422` | TLD-specific validation failure (e.g. missing organization for certain country-code TLDs). | Full error envelope: [Errors](https://developer.godaddy.com/docs/api-users/errors). ## Reference * [v1 domain settings — `PATCH /v1/domains/{domain}/contacts`](https://developer.godaddy.com/docs/references/rest/domains/v1/update-contacts) ## Next # How to register a domain (https://developer.godaddy.com/en/docs/api-users/domains/register) --- title: How to register a domain description: Register a domain using the GoDaddy Domains API. keywords: >- buy domain, purchase domain, POST /v3/domains/registrations, Idempotency-Key, consent object, agreedAt, agreementTypes, QUOTE_MISMATCH, ICANN consent agentNotes: permissions: - Domain Registration scopes: - 'domains.domain:read' - 'domains.domain:create' rateLimit: >- Rate-limited per credential per window. Go to /docs/api-users/rate-limits for current values. idempotent: false destructive: false failureRecovery: >- Registration charges the account and is not reversible. Use the Idempotency-Key header to prevent duplicate purchases. If the operation status is EXECUTING, poll — do not resubmit. related: apis: - title: v3 Register Domain href: /docs/references/rest/domains/v3/register-domain - title: v3 Registration Quotes href: /docs/references/rest/domains/v3/quote-domain-registration guides: - title: Search domain availability href: /docs/api-users/domains/search - title: Manage DNS records href: /docs/api-users/domains/manage/dns - title: Set up a payment profile href: /docs/api-users/payment-profile concepts: - title: Authentication href: /docs/api-users/auth - title: Error handling href: /docs/api-users/errors --- ## Overview This guide covers registering a domain programmatically using the GoDaddy Domains API. Registration charges the account's billing method and isn't reversible. Make sure you have a [payment method on file](https://developer.godaddy.com/docs/api-users/payment-profile) before registering. The v3 API registers one domain per call. There's no batch endpoint that combines multiple domains into a single transaction. To register 20 domains, make 20 separate calls to `POST /v3/domains/registrations`, each with a unique `Idempotency-Key`. Each call is an independent charge event. `GET /v3/domains/check-availability`, `POST /v3/domains/check-availability`, and `POST /v3/domains/registration-quotes` are read-only and never charge. Only `POST /v3/domains/registrations` charges the account. ICANN requires that registrant contact information be accurate. Providing false contact information can result in domain suspension. Use WHOIS privacy after registration if you want to protect your contact details. Don't enter fake data. ## Prerequisites * a GoDaddy account with a payment method on file Go to [Create account](https://sso.godaddy.com/account/create/) to create a GoDaddy account and add or update payment methods. * a [PAT](https://developer.godaddy.com/docs/api-users/auth) with `domains.domain:create` scope * a registrant contact with name, email, phone, and mailing address * a confirmed available domain * *(optional)* the [GoDaddy CLI](https://developer.godaddy.com/docs/api-users/cli/set-up) installed and configured ## Register a domain v3 separates pricing from execution. You get a price quote first, locking a `quoteToken`, then execute the registration with that token. This ensures the price you agreed to is the price charged. Always poll at least once even if the initial response appears synchronous. v3 does not accept inline payment or registrant contact overrides. The billing method and registrant contact are resolved from the account profile. If the account is missing a payment method or required contact fields, the quote returns `422` with field-level details. ### Check availability Confirm the domain is available before quoting. * Run the availability check: ```bash tab="curl" curl -s "https://api.godaddy.com/v3/domains/check-availability?domain=example.com" \ -H "Authorization: Bearer $GODADDY_PAT" ``` ```js tab="Node" const res = await fetch( "https://api.godaddy.com/v3/domains/check-availability?domain=example.com", { headers: { Authorization: `Bearer ${process.env.GODADDY_PAT}` } } ); const { available } = await res.json(); if (!available) throw new Error("Domain not available"); ``` ```python tab="Python" import os, requests res = requests.get( "https://api.godaddy.com/v3/domains/check-availability", params={"domain": "example.com"}, headers={"Authorization": f"Bearer {os.environ['GODADDY_PAT']}"}, ) data = res.json() assert data["available"], "Domain not available" ``` ```go tab="Go" package main import ( "encoding/json" "fmt" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://api.godaddy.com/v3/domains/check-availability?domain=example.com", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT")) res, _ := http.DefaultClient.Do(req) defer res.Body.Close() var data struct{ Available bool `json:"available"` } json.NewDecoder(res.Body).Decode(&data) if !data.Available { panic("not available") } fmt.Println("available") } ``` ```bash tab="CLI" gddy domain available example.com ``` Go to [Search availability](https://developer.godaddy.com/docs/api-users/domains/search) for bulk checks and suggestions. ### Get a registration quote `POST /v3/domains/registration-quotes` locks the price and returns the `requiredAgreements` list you need for the next step. The `quoteToken` guarantees the price you see is the price charged at registration. * Get a quote: ```bash tab="curl" curl -s -X POST "https://api.godaddy.com/v3/domains/registration-quotes" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "Content-Type: application/json" \ -d '{"domain": "example.com", "period": 1}' ``` ```js tab="Node" const res = await fetch("https://api.godaddy.com/v3/domains/registration-quotes", { method: "POST", headers: { Authorization: `Bearer ${process.env.GODADDY_PAT}`, "Content-Type": "application/json", }, body: JSON.stringify({ domain: "example.com", period: 1 }), }); const { quoteToken, expiresAt, requiredAgreements } = await res.json(); console.log("Quote locked until", expiresAt); ``` ```python tab="Python" import os, requests res = requests.post( "https://api.godaddy.com/v3/domains/registration-quotes", json={"domain": "example.com", "period": 1}, headers={ "Authorization": f"Bearer {os.environ['GODADDY_PAT']}", "Content-Type": "application/json", }, ) res.raise_for_status() quote = res.json() required_agreements = quote["requiredAgreements"] print("Quote locked until", quote["expiresAt"]) ``` ```go tab="Go" package main import ( "bytes" "encoding/json" "fmt" "net/http" "os" ) func main() { body := bytes.NewReader([]byte(`{"domain": "example.com", "period": 1}`)) req, _ := http.NewRequest("POST", "https://api.godaddy.com/v3/domains/registration-quotes", body) req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT")) req.Header.Set("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() var quote struct { QuoteToken string `json:"quoteToken"` ExpiresAt string `json:"expiresAt"` RequiredAgreements []struct { AgreementType string `json:"agreementType"` Title string `json:"title"` URL string `json:"url"` } `json:"requiredAgreements"` } json.NewDecoder(res.Body).Decode("e) fmt.Println("Quote locked until", quote.ExpiresAt) } ``` ```bash tab="CLI" gddy domain quote example.com ``` ```json { "quoteToken": "qt_abc123...", "expiresAt": "2026-01-15T10:45:00.000Z", "requiredAgreements": [ { "agreementType": "API_DPA", "title": "API Domain Purchase Agreement", "url": "https://www.godaddy.com/agreements/showdoc?pageid=reg_sa" } ], "items": [ { "domain": "example.com", "period": 1, "price": { "currencyCode": "USD", "value": 1199 } } ] } ``` `price.value` is in minor currency units — cents for USD, so `1199` = $11.99. Divide by 100 for display. The `quoteToken` expires after a short window. If it expires before you execute, fetch a new quote. Some domains — such as aftermarket premium names — carry a one-time purchase fee in addition to the registration price. When the quote response includes a `fees` array on any item, you must pass `acknowledgedFees` in the `consent` object when you execute. The entries must match the quote's `fees` verbatim (same `type`, amount, and currency). A mismatch returns `422 QUOTE_MISMATCH`. When `fees` is non-empty, include `acknowledgedFees` in `consent`: ```json { "consent": { "agreedAt": "2026-01-15T10:30:00.000Z", "agreementTypes": ["API_DPA"], "acknowledgedFees": [ { "type": "ONE_TIME_PREMIUM_DOMAIN_PURCHASE", "fee": { "currencyCode": "USD", "value": 390000 } } ] } } ``` ### Review the required agreements The quote response includes a `requiredAgreements` list (the legal agreements you need to review before you submit the registration). Each item has a `title` for display and a `url` linking to the full legal text. The GoDaddy CLI handles agreement acceptance through the `--agree` flag on `gddy domain purchase`. Skip to [Submit the registration](#submit-the-registration) and pass `--agree` to confirm consent. 1. Display each agreement to the user: ```js tab="Node" for (const agreement of requiredAgreements) { console.log(`Review: ${agreement.title}`); console.log(`Full text: ${agreement.url}`); } ``` ```python tab="Python" for agreement in required_agreements: print(f"Review: {agreement['title']}") print(f"Full text: {agreement['url']}") ``` ```go tab="Go" for _, agreement := range quote.RequiredAgreements { fmt.Println("Review:", agreement.Title) fmt.Println("Full text:", agreement.URL) } ``` 2. After the user confirms, capture the agreement types and consent timestamp: ```js tab="Node" const agreedAt = new Date().toISOString(); const agreedTypes = requiredAgreements.map((a) => a.agreementType); ``` ```python tab="Python" from datetime import datetime, timezone agreed_at = datetime.now(timezone.utc).isoformat() agreed_types = [a["agreementType"] for a in required_agreements] ``` ```go tab="Go" agreedAt := time.Now().UTC().Format(time.RFC3339) agreedTypes := make([]string, len(quote.RequiredAgreements)) for i, a := range quote.RequiredAgreements { agreedTypes[i] = a.AgreementType } ``` Use the actual timestamp of when the user clicked accept for `agreedAt` — not the time of the API call. Synthetic timestamps violate ICANN policy. Required agreements depend on the TLD. `.ca` domains require a CIRA agreement, `.au` domains require an AURA agreement. Always use the `agreementType` values from `requiredAgreements` — don't hardcode them. ### Submit the registration Send the `quoteToken` and consent to execute the registration. Always include an `Idempotency-Key` header — if the request times out or returns `5xx`, replay with the same key and the server deduplicates. `POST /v3/domains/registrations` charges the account's billing method. Verify the domain name and the quoted price before executing. * Submit the registration request: ```bash tab="curl" curl -s -X POST "https://api.godaddy.com/v3/domains/registrations" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "quoteToken": "qt_abc123...", "domain": "example.com", "period": 1, "consent": { "agreedAt": "2026-01-15T10:30:00.000Z", "agreementTypes": ["API_DPA"] } }' ``` ```js tab="Node" import { randomUUID } from "node:crypto"; const res = await fetch("https://api.godaddy.com/v3/domains/registrations", { method: "POST", headers: { Authorization: `Bearer ${process.env.GODADDY_PAT}`, "Content-Type": "application/json", "Idempotency-Key": randomUUID(), }, body: JSON.stringify({ quoteToken: "qt_abc123...", domain: "example.com", period: 1, consent: { agreedAt, // timestamp captured in step 3 agreementTypes: agreedTypes, // types from requiredAgreements in step 3 }, }), }); if (!res.ok) throw new Error(`Registration failed: ${res.status}`); const { registrationId, domain } = await res.json(); console.log("Registered:", domain, "registrationId:", registrationId); ``` ```python tab="Python" import os, uuid, requests res = requests.post( "https://api.godaddy.com/v3/domains/registrations", json={ "quoteToken": "qt_abc123...", "domain": "example.com", "period": 1, "consent": { "agreedAt": agreed_at, # timestamp captured in step 3 "agreementTypes": agreed_types, # types from requiredAgreements in step 3 }, }, headers={ "Authorization": f"Bearer {os.environ['GODADDY_PAT']}", "Content-Type": "application/json", "Idempotency-Key": str(uuid.uuid4()), }, ) res.raise_for_status() data = res.json() print("Registered:", data["domain"], "registrationId:", data["registrationId"]) ``` ```go tab="Go" package main import ( "bytes" "encoding/json" "fmt" "net/http" "os" "time" "github.com/google/uuid" ) func main() { body := map[string]any{ "quoteToken": "qt_abc123...", "domain": "example.com", "period": 1, "consent": map[string]any{ "agreedAt": agreedAt, // timestamp captured in step 3 "agreementTypes": agreedTypes, // types from requiredAgreements in step 3 }, } b, _ := json.Marshal(body) req, _ := http.NewRequest("POST", "https://api.godaddy.com/v3/domains/registrations", bytes.NewReader(b)) req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT")) req.Header.Set("Content-Type", "application/json") req.Header.Set("Idempotency-Key", uuid.NewString()) res, _ := http.DefaultClient.Do(req) defer res.Body.Close() if res.StatusCode != 202 { panic(fmt.Sprint("registration failed: ", res.StatusCode)) } var reg struct { RegistrationID string `json:"registrationId"` Domain string `json:"domain"` } json.NewDecoder(res.Body).Decode(®) fmt.Println("Registered:", reg.Domain, "registrationId:", reg.RegistrationID) } ``` ```bash tab="CLI" # Run without --agree first to review required agreements, then add --agree to confirm. # --confirm skips the interactive prompt. gddy domain purchase --quote-token --agree --confirm ``` Use the actual consent timestamp for `agreedAt`; synthetic values violate ICANN policy. Use the `agreementTypes` keys from `requiredAgreements` in the quote response; the registration returns `INVALID_AGREEMENT_KEYS` if they don't match. The `period` must match the quoted period, or you get `QUOTE_MISMATCH`. If you supplied a `profile` or `profileId` at quote time, re-supply the same value on execute or you get `QUOTE_MISMATCH`. The `Idempotency-Key` must be a unique UUID per attempt; retrying with the same key is safe after a timeout. ### Poll the operation The registration is asynchronous. Poll the returned `registrationId` URL every few seconds until the status reaches a terminal state. The GoDaddy CLI polls automatically after `gddy domain purchase` and exits when the operation reaches a terminal state. No manual polling required. * Poll for the registration status: ```bash tab="curl" curl -s "https://api.godaddy.com/v3/domains/registrations/{registrationId}" \ -H "Authorization: Bearer $GODADDY_PAT" ``` ```js tab="Node" async function pollRegistration(registrationId, intervalMs = 3000) { while (true) { const res = await fetch( `https://api.godaddy.com/v3/domains/registrations/${registrationId}`, { headers: { Authorization: `Bearer ${process.env.GODADDY_PAT}` } } ); const { status, domain } = await res.json(); if (status === "COMPLETED") return domain; if (status === "FAILED") throw new Error("Registration failed"); await new Promise((r) => setTimeout(r, intervalMs)); } } ``` ```python tab="Python" import os, time, requests def poll_registration(registration_id, interval=3): while True: res = requests.get( f"https://api.godaddy.com/v3/domains/registrations/{registration_id}", headers={"Authorization": f"Bearer {os.environ['GODADDY_PAT']}"}, ) data = res.json() if data["status"] == "COMPLETED": return data["domain"] if data["status"] == "FAILED": raise RuntimeError("Registration failed") time.sleep(interval) ``` ```go tab="Go" package main import ( "encoding/json" "fmt" "net/http" "os" "time" ) func pollRegistration(registrationID string) { for { req, _ := http.NewRequest("GET", "https://api.godaddy.com/v3/domains/registrations/"+registrationID, nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT")) res, _ := http.DefaultClient.Do(req) var data struct { Status string `json:"status"` } json.NewDecoder(res.Body).Decode(&data) res.Body.Close() switch data.Status { case "COMPLETED": fmt.Println("Registration complete") return case "FAILED": panic("Registration failed") } time.Sleep(3 * time.Second) } } ``` | Status | Meaning | | ----------- | ------------------------------------------------------------- | | `CONFIRMED` | Accepted, processing in progress. Keep polling. | | `EXECUTING` | Actively executing. Keep polling. | | `COMPLETED` | Terminal — succeeded. `domain` and `expiresAt` are populated. | | `FAILED` | Terminal — failed. | You can also poll through `GET /v3/domains/operations/{operationId}`. Both endpoints resolve the same resource. ## Registration body fields The following table lists the fields required for the registration body. | Field | Required | Description | | ------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | `quoteToken` | Yes | Token from `POST /v3/domains/registration-quotes`. | | `domain` | Yes | Fully-qualified domain name to register. | | `period` | Yes | Registration period in years (must match the quoted period). | | `consent` | Yes | ICANN consent object capturing the agreement type, consenting party, and timestamp listed in the [Consent object fields](#consent-object-fields) table. | | `Idempotency-Key` header | Yes | UUID generated per request. | ## Consent object fields The following table lists the fields required for the consent object. | Field | Required | Description | Note | | ------------------ | ----------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | `agreementTypes` | Yes | Agreement type keys from the TLD's required agreements (for example, `API_DPA`). | Get these from the `requiredAgreements` field in the quote response. | | `agreedAt` | Yes | Actual ISO 8601 timestamp of when the user consented. | | | `acknowledgedFees` | When fees present | Fee entries from the quote that the user explicitly acknowledged. | Required when the quote's `fees` array is non-empty. Entries must match verbatim; a mismatch returns `422 QUOTE_MISMATCH`. | ## Common errors The following table lists common errors and recommended actions. Go to [Errors](https://developer.godaddy.com/docs/api-users/errors) for the full error envelope. | Status | Most likely cause | Recommended action | | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | `400` | Malformed request body or missing required field. | Inspect `fields[]` in the error response. | | `403` | Credential lacks write access, no [payment method on file](https://developer.godaddy.com/docs/api-users/payment-profile), or account billing issue. | Check `code` to distinguish. | | `404` | TLD not supported. | | | `409` | Domain is already registered (by anyone). | | | `422 QUOTE_MISMATCH` | The `period`, `profile`/`profileId`, or `acknowledgedFees` in the execute body don't match the quote. | Re-use the same `period`, `profile`, `profileId`, and `acknowledgedFees` from the quote, or fetch a new quote. | | `422 INVALID_AGREEMENT_KEYS` | Wrong `agreementTypes` value. | Use the keys returned in `requiredAgreements` from the quote response. | | `422 MISSING_CONTACT` | No registrant contact on the account profile. | Add a registrant contact to the account profile. | | `422 MISSING_BILLING_PHONE` | Contact phone is missing or malformed. | Verify `phone.countryCode` and `phone.nationalNumber` are both set. | | `422` | Domain isn't available, missing or invalid consent, or other contact validation failure. | Inspect `fields[]` for specifics. | ## Additional information * [v3 Registrations — `POST /v3/domains/registrations`](https://developer.godaddy.com/docs/references/rest/domains/v3/register-domain) * [v3 Registration Quotes — `POST /v3/domains/registration-quotes`](https://developer.godaddy.com/docs/references/rest/domains/v3/quote-domain-registration) * [v3 Operations — `GET /v3/domains/operations/{operationId}`](https://developer.godaddy.com/docs/references/rest/domains/v3/get-operation) * [v1 registration and renewals — `POST /v1/domains/purchase`](https://developer.godaddy.com/docs/references/rest/domains/v1/purchase) # How to search domain availability (https://developer.godaddy.com/en/docs/api-users/domains/search) --- title: How to search domain availability description: >- Check whether a domain is available to register, or get natural-language suggestions for alternatives. Both operations are available through the v3 API. keywords: >- check domain available, is domain available, domain lookup, find domain name, check-availability endpoint, AVAILABLE UNAVAILABLE, optimizeFor ACCURACY, firstTermPrice. agentNotes: permissions: - Domain Search scopes: - 'domains.domain:read' idempotent: true destructive: false failureRecovery: >- Safe to retry on any error. Results are cached; use optimizeFor=ACCURACY for live registry checks. related: apis: - title: 'Domains v3: Check Availability' href: /docs/references/rest/domains/v3/get-domain-availability guides: - title: Register a domain href: /docs/api-users/domains/register - title: Manage DNS records href: /docs/api-users/domains/manage/dns concepts: - title: Authentication href: /docs/api-users/auth - title: Rate limits href: /docs/api-users/rate-limits --- ## Overview Search operations let you check whether a specific domain is available for registration, and discover alternative names based on keywords or natural-language queries. Both operations are read-only, require no payment method, and return indicative pricing alongside results. ## v3 (recommended) v3 offers two discovery operations: a single-domain availability check and a suggestions endpoint that returns available alternatives for a natural-language query. ### Check availability `GET /v3/domains/check-availability?domain={domain}` returns availability and per-term pricing for a single domain. The following procedure checks whether a domain is available to register. * Run the following command for your preferred language: ```bash tab="curl" curl -s "https://api.godaddy.com/v3/domains/check-availability?domain=your-idea.com" \ -H "Authorization: Bearer $GODADDY_PAT" ``` ```js tab="Node" const pat = process.env.GODADDY_PAT; const url = new URL("https://api.godaddy.com/v3/domains/check-availability"); url.searchParams.set("domain", "your-idea.com"); const res = await fetch(url, { headers: { Authorization: `Bearer ${pat}` }, }); const result = await res.json(); console.log(result.available, result.prices?.[0]?.price); ``` ```python tab="Python" import os, requests pat = os.environ["GODADDY_PAT"] res = requests.get( "https://api.godaddy.com/v3/domains/check-availability", params={"domain": "your-idea.com"}, headers={"Authorization": f"Bearer {pat}"}, ) data = res.json() print(data["available"], data["prices"][0]["price"]) ``` ```go tab="Go" package main import ( "encoding/json" "fmt" "net/http" "os" ) func main() { pat := os.Getenv("GODADDY_PAT") req, _ := http.NewRequest("GET", "https://api.godaddy.com/v3/domains/check-availability?domain=your-idea.com", nil) req.Header.Set("Authorization", "Bearer "+pat) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() var result struct { Available bool `json:"available"` Prices []map[string]any `json:"prices"` } json.NewDecoder(res.Body).Decode(&result) fmt.Println(result.Available, result.Prices) } ``` ```bash tab="CLI" gddy domain available your-idea.com # For a live registry check (bypasses cache): gddy domain available your-idea.com --check-type full ``` | Parameter | Required | Description | Note | | ------------- | -------- | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- | | `domain` | Yes | Fully-qualified domain name to check. | IDN values must be in punycode A-label form. | | `optimizeFor` | No | `SPEED` (default, cached) or `ACCURACY` (live registry check, higher latency). | Availability is always re-verified at quote time regardless of this setting. | | `iscCode` | No | ISC discount code for pricing context. | When provided, prices reflect the applicable rates for this ISC. | Response includes availability and indicative per-term pricing: ```json { "domain": "your-idea.com", "available": true, "definitive": false, "inventory": "REGISTRY", "prices": [ { "term": "YEAR", "period": 1, "price": { "currencyCode": "USD", "value": 1199 }, "renewalPrice": { "currencyCode": "USD", "value": 2299 } }, { "term": "YEAR", "period": 2, "price": { "currencyCode": "USD", "value": 3098 }, "renewalPrice": { "currencyCode": "USD", "value": 4598 }, "firstTermPrice": { "currencyCode": "USD", "value": 799 } } ] } ``` `prices[]` contains one entry per available registration term. All price values are in cents. Prices from availability checks are indicative. The authoritative price is locked when you call `POST /v3/domains/registration-quotes`. Go to [Register a domain](https://developer.godaddy.com/docs/api-users/domains/register) for the full quote-execute flow. Reference: [`GET /v3/domains/check-availability`](https://developer.godaddy.com/docs/references/rest/domains/v3/get-domain-availability) ### Get suggestions `GET /v3/domains/suggestions` returns available domain name suggestions for a natural-language query or keyword set. All results are available without filtering required. The following procedure gets domain name suggestions for a query. * Run the following command for your preferred language: ```bash tab="curl" curl -s "https://api.godaddy.com/v3/domains/suggestions?query=sunrise+bakery&tlds=com,net,shop&pageSize=10" \ -H "Authorization: Bearer $GODADDY_PAT" ``` ```js tab="Node" const pat = process.env.GODADDY_PAT; const url = new URL("https://api.godaddy.com/v3/domains/suggestions"); url.searchParams.set("query", "sunrise bakery"); url.searchParams.set("tlds", "com,net,shop"); url.searchParams.set("pageSize", "10"); const res = await fetch(url, { headers: { Authorization: `Bearer ${pat}` }, }); const { items } = await res.json(); items.forEach((item) => console.log(item.domain, item.prices?.[0]?.price)); ``` ```python tab="Python" import os, requests pat = os.environ["GODADDY_PAT"] res = requests.get( "https://api.godaddy.com/v3/domains/suggestions", params={"query": "sunrise bakery", "tlds": "com,net,shop", "pageSize": 10}, headers={"Authorization": f"Bearer {pat}"}, ) for item in res.json()["items"]: print(item["domain"], item["prices"][0]["price"]) ``` ```go tab="Go" package main import ( "encoding/json" "fmt" "net/http" "net/url" "os" ) func main() { pat := os.Getenv("GODADDY_PAT") u, _ := url.Parse("https://api.godaddy.com/v3/domains/suggestions") q := u.Query() q.Set("query", "sunrise bakery") q.Set("tlds", "com,net,shop") q.Set("pageSize", "10") u.RawQuery = q.Encode() req, _ := http.NewRequest("GET", u.String(), nil) req.Header.Set("Authorization", "Bearer "+pat) res, _ := http.DefaultClient.Do(req) defer res.Body.Close() var body struct { Items []struct{ Domain string `json:"domain"` } `json:"items"` } json.NewDecoder(res.Body).Decode(&body) for _, item := range body.Items { fmt.Println(item.Domain) } } ``` ```bash tab="CLI" gddy domain suggest "your idea" --tlds com --tlds app --limit 10 ``` | Parameter | Required | Description | Note | | ----------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------ | | `query` | No | Natural-language query or keywords. | For example, `sunrise bakery`. | | `tlds` | No | Comma-separated TLDs to include. | For example, `com,net,shop`. | | `pageSize` | No | Number of suggestions to return. | 1–50, default `10`. | | `lengthMin` | No | Minimum second-level domain length. | | | `lengthMax` | No | Maximum second-level domain length. | | | `sources` | No | Comma-separated suggestion strategies: `EXTENSION` (vary TLD), `KEYWORD_SPIN` (rotate keywords), `CC_TLD` (country-code TLDs), `PREMIUM` (include premium-priced names). | | Response is an object with an `items` array. Each entry includes the domain name and indicative per-term pricing: ```json { "items": [ { "domain": "sunrisebakery.com", "inventory": "REGISTRY", "prices": [ { "term": "YEAR", "period": 1, "price": { "currencyCode": "USD", "value": 1199 }, "renewalPrice": { "currencyCode": "USD", "value": 2299 } }, { "term": "YEAR", "period": 2, "price": { "currencyCode": "USD", "value": 3098 }, "renewalPrice": { "currencyCode": "USD", "value": 4598 }, "firstTermPrice": { "currencyCode": "USD", "value": 799 } } ] } ] } ``` `price.value` and `renewalPrice.value` are in cents. Divide by 100 for the display price. Reference: [`GET /v3/domains/suggestions`](https://developer.godaddy.com/docs/references/rest/domains/v3/suggest-domains) ## Read the response All price objects use `{currencyCode, value}` where `value` is an integer in cents. Divide by 100 for the display price. For example, `{"currencyCode": "USD", "value": 1199}` displays as `$11.99`. Each entry in `prices[]` is a registration term with these fields: | Field | Description | | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `period` | Registration length (1 = one year, 2 = two years, etc.). | | `term` | Unit of the period. Currently always `YEAR`. | | `price` | Total registration price for this term. Always present. | | `renewalPrice` | Renewal price when the domain comes up for renewal. Absent when unavailable or identical to `price`. | | `firstTermPrice` | Discounted price for the first year of a multi-year registration, when a first-year promotion applies. Typically absent when `period` is 1. When present, the first year costs `firstTermPrice`; the remaining years account for the rest of `price`. | | `recommended` | `true` when this term is the best-value option based on active discounts. Use this flag to highlight a suggested term in your UI. | ## Common errors | Status | Most likely cause | | ------ | ----------------------------------------------------------------------------------------- | | `400` | Malformed request: domain missing, not a valid FQDN, or invalid query parameter. | | `401` | Authentication credentials are missing or invalid. | | `403` | Caller is not authorized. Check that your token includes the `domains.domain:read` scope. | | `429` | Rate limit exceeded. Honor the `Retry-After` header before retrying. | | `5xx` | Upstream registry timeout. Safe to retry: availability checks are idempotent. | ## Additional information # How to build an API integration (https://developer.godaddy.com/en/docs/api-users/domains/workflows/api-integration) --- title: How to build an API integration description: >- End-to-end workflow — set up credentials, make authenticated calls, handle errors, and prepare for production. keywords: >- export GODADDY_PAT, generate token, developer setup, first API call, retryAfterSec, 429 handling, production checklist, integration tutorial agentNotes: permissions: - Any account scopes: - 'domains.domain:read (minimum for example calls in this guide)' rateLimit: >- Rate-limited per credential per window. Go to /docs/api-users/rate-limits for current values. idempotent: true destructive: false failureRecovery: >- All calls in this guide are read-only. Safe to retry any failure. On 401, verify the token is exported correctly. On 429, implement exponential backoff with the Retry-After header. related: apis: - title: Domains v3 reference href: /docs/references/rest/domains/v3 guides: - title: Quickstart href: /docs/api-users/quickstart - title: Authenticate href: /docs/api-users/auth - title: Handle errors href: /docs/api-users/errors - title: Rate limits href: /docs/api-users/rate-limits --- ## Overview This workflow takes you from zero to a production-ready API integration. It covers credential setup, your first call, error handling patterns, and the operational considerations for running in production. ## Prerequisites The following prerequisites are required before you build an API integration: * A GoDaddy account (create one at [sso.godaddy.com](https://sso.godaddy.com/account/create/)) * A terminal with `curl`, or Node.js / Python installed ## Generate a Personal Access Token The following procedure generates a Personal Access Token (PAT) for authenticating API calls. 1. Sign in to the [Personal Access Token](https://developer.godaddy.com/personal-access-token) page. 2. Click **+ Generate Token**. 3. Select the scopes your integration needs (at minimum, `domains.domain:read` for read operations). 4. Copy the token immediately (it only displays once). 5. Export the credential: ```bash export GODADDY_PAT="" ``` Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for the full scope reference and environment guidance. ## Make your first authenticated call The following procedure verifies your token works with a simple availability check. A successful response returns JSON with `available`, `prices`, and other fields. If you get a `401`, check that the token is correctly set in the environment variable. * Run the request: ```bash curl -s "https://api.godaddy.com/v3/domains/check-availability?domain=example-test.com" \ -H "Authorization: Bearer $GODADDY_PAT" ``` Go to the [quickstart](https://developer.godaddy.com/docs/api-users/quickstart) for a detailed walkthrough of this call. ## Handle errors gracefully The following procedure implements error handling for API responses. Every error response follows the same envelope. Match on `code`, not `message`. Build a switch/match statement for the codes you expect. 1. Examine the error shape: ```json { "code": "STABLE_ERROR_CODE", "message": "Human-readable description", "fields": [] } ``` 2. Implement error handling: ```js const res = await fetch(url, { headers }); if (!res.ok) { const err = await res.json(); switch (err.code) { case "QUOTA_EXCEEDED": await sleep(err.retryAfterSec * 1000); return retry(url, headers); case "UNAUTHORIZED": throw new Error("Token expired or invalid"); default: throw new Error(`API error: ${err.code}`); } } ``` Go to [Handle errors](https://developer.godaddy.com/docs/api-users/errors) for the full status code reference and retry semantics. ## Add rate limit handling When you apply rate limiting use the following strategies to stay under the limit: * Use bulk endpoints where available (e.g., `POST /v1/domains/available` for batch checks) * Cache availability results briefly when `definitive: false` * Use cursor pagination instead of parallel page-walks The following procedure adds rate limit handling to your integration. The API enforces a per-credential, windowed rate limit — go to [Rate limits](https://developer.godaddy.com/docs/api-users/rate-limits) for current values. * Implement retry logic that respects the `retryAfterSec` field: ```js async function callWithRetry(url, headers, attempts = 3) { for (let i = 0; i < attempts; i++) { const res = await fetch(url, { headers }); if (res.status !== 429) return res; const { retryAfterSec } = await res.json(); const jitter = Math.random() * 1000; await new Promise(r => setTimeout(r, retryAfterSec * 1000 + jitter)); } throw new Error("Rate limit retries exhausted"); } ``` Go to [Handle rate limits](https://developer.godaddy.com/docs/api-users/rate-limits) for the full strategy guide. ## Production readiness checklist Before deploying to production, verify: | Concern | Action | | ----------------------- | ------------------------------------------------------------------ | | **Credential security** | PAT stored in a secrets manager, never committed to source control | | **Error handling** | All expected error codes handled with appropriate user feedback | | **Rate limiting** | Exponential backoff with jitter implemented | | **Idempotency** | Write operations use `Idempotency-Key` header where supported | | **Monitoring** | Log `code` field from error responses for alerting | | **Pagination** | List operations use cursor pagination, not parallel fetches | | **Environment** | Production PAT targeting `api.godaddy.com` | # How to register and configure a domain (https://developer.godaddy.com/en/docs/api-users/domains/workflows/domain-lifecycle) --- title: How to register and configure a domain description: >- End-to-end workflow — search for a domain, register it, configure DNS, and verify the setup. keywords: >- domain lifecycle, availability check flow, quote execute flow, buy configure domain, Idempotency-Key header, poll registration, configure DNS after registration agentNotes: permissions: - Domain Registration - DNS Management scopes: - 'domains.domain:read' - 'domains.domain:create' - 'domains.dns:update' rateLimit: >- Rate-limited per credential per window. Go to /docs/api-users/rate-limits for current values. idempotent: false destructive: false failureRecovery: >- Registration charges the account and is not reversible. Use the Idempotency-Key header on POST /v3/domains/registrations to prevent duplicate charges. If a step fails mid-workflow, poll the operation URL before retrying the registration step. DNS writes are safe to retry. related: apis: - title: v3 Registrations href: /docs/references/rest/domains/v3/register-domain - title: v3 Registration Quotes href: /docs/references/rest/domains/v3/quote-domain-registration guides: - title: Quickstart href: /docs/api-users/quickstart - title: Search domain availability href: /docs/api-users/domains/search - title: Register a domain href: /docs/api-users/domains/register - title: Manage DNS records href: /docs/api-users/domains/manage/dns - title: Set up a payment profile href: /docs/api-users/payment-profile - title: Authentication href: /docs/api-users/auth - title: Handle errors href: /docs/api-users/errors - title: Handle rate limits href: /docs/api-users/rate-limits --- ## Overview This workflow walks through the complete domain lifecycle from search to live configuration. By the end, you'll have a registered domain with DNS records serving traffic. Code examples are available in curl, Node, Python, and Go. ## Prerequisites The following prerequisites are required before you register and configure a domain: * A GoDaddy account with a [payment profile](https://developer.godaddy.com/docs/api-users/payment-profile) configured * A [Personal Access Token](https://developer.godaddy.com/docs/api-users/auth) with `domains.domain:read`, `domains.domain:create`, and `domains.dns:update` scopes, exported as `GODADDY_PAT`; also export `BASE=https://api.godaddy.com` for the multi-language examples * A terminal with `curl`, or Node.js, Python, or Go ## Search for an available domain The following procedure checks whether your desired domain is available for registration. 1. Check availability: ```bash tab="curl" curl -s "https://api.godaddy.com/v3/domains/check-availability?domain=your-idea.com" \ -H "Authorization: Bearer $GODADDY_PAT" ``` ```bash tab="CLI" gddy domain available your-idea.com ``` If `available` is `true`, proceed to quoting. If `false`, use the suggestions endpoint to find alternatives. 2. Get suggestions: ```bash tab="curl" curl -s "https://api.godaddy.com/v3/domains/suggestions?query=your+idea&tlds=com,net,io&pageSize=10" \ -H "Authorization: Bearer $GODADDY_PAT" ``` ```bash tab="CLI" gddy domain suggest "your idea" --tlds com --tlds net --tlds io --limit 10 ``` Go to [Search domain availability](https://developer.godaddy.com/docs/api-users/domains/search) for the full parameter reference. ## Get a registration quote The following procedure locks in a price by requesting a quote. The `quoteToken` in the response is valid for 10 minutes. 1. Request a quote: ```bash tab="curl" curl -s -X POST "https://api.godaddy.com/v3/domains/registration-quotes" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "Content-Type: application/json" \ -d '{ "domain": "your-idea.com", "period": 1 }' ``` ```bash tab="CLI" gddy domain quote your-idea.com ``` 2. Note the `quoteToken` and `requiredAgreements` from the response (you'll need both for the next step). The GoDaddy CLI stores the token and handles agreement acceptance automatically through `--agree`. ## Execute the registration The following procedure submits the registration using the quote token and ICANN consent. Registration applies charges to your payment profile and is not reversible. Verify the domain name and quoted price before executing. * Submit the registration: ```bash tab="curl" curl -s -X POST "https://api.godaddy.com/v3/domains/registrations" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "quoteToken": "", "domain": "your-idea.com", "period": 1, "consent": { "agreedAt": "2026-01-15T10:30:00.000Z", "agreementTypes": ["API_DPA"] } }' ``` ```bash tab="CLI" # Run without --agree first to review required agreements, then add --agree to confirm. gddy domain purchase your-idea.com --agree --confirm ``` Go to [Register a domain](https://developer.godaddy.com/docs/api-users/domains/register) for the full field reference and error handling. ## Poll until complete The following procedure polls the registration status. Registration is asynchronous. Poll the returned operation URL until the status reaches a terminal state. The following table lists the possible statuses: | Status | Meaning | | ----------- | ----------------------------------------------- | | `CONFIRMED` | Accepted, processing. Keep polling. | | `EXECUTING` | In progress. Keep polling. | | `COMPLETED` | Registration succeeded. | | `FAILED` | Registration failed. Check `error` for details. | The GoDaddy CLI polls automatically after `gddy domain purchase` and exits when registration reaches a terminal state. No manual polling required. * Poll the registration: ```bash curl -s "$BASE/v3/domains/registrations/" \ -H "Authorization: Bearer $GODADDY_PAT" ``` ## Add DNS records The following procedure adds DNS records to point the domain at your infrastructure. Run these after registration completes. 1. Add an A record for the apex: ```bash tab="curl" curl -s -X POST "https://api.godaddy.com/v3/domains/zones/your-idea.com/dns-records" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "Content-Type: application/json" \ -d '{ "type": "A", "name": "@", "data": "192.0.2.1", "ttl": 600 }' ``` ```bash tab="CLI" gddy dns add your-idea.com --type A --name @ --data 192.0.2.1 --ttl 600 ``` 2. Add additional records as needed (CNAME for `www`, MX for email, TXT for verification): ```bash tab="curl" curl -s -X POST "https://api.godaddy.com/v3/domains/zones/your-idea.com/dns-records" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "Content-Type: application/json" \ -d '{ "type": "CNAME", "name": "www", "data": "your-idea.com", "ttl": 600 }' ``` ```bash tab="CLI" gddy dns add your-idea.com --type CNAME --name www --data your-idea.com --ttl 600 ``` Go to [Manage DNS records](https://developer.godaddy.com/docs/api-users/domains/manage/dns) for the full record type reference. ## Verify DNS propagation The following procedure verifies that your DNS records were created and are propagating. * List your records to confirm they were created: ```bash tab="curl" curl -s "https://api.godaddy.com/v3/domains/zones/your-idea.com/dns-records" \ -H "Authorization: Bearer $GODADDY_PAT" ``` ```bash tab="CLI" gddy dns list your-idea.com ``` DNS changes propagate within minutes for GoDaddy-hosted nameservers. External resolvers may cache the old state for up to the previous TTL value. # How to list and look up mailboxes (https://developer.godaddy.com/en/docs/api-users/email/mailboxes/manage-mailboxes) --- title: How to list and look up mailboxes description: >- List mailboxes across your domains, filter and paginate the results, and look up a single mailbox. keywords: >- list mailboxes, GET /v1/email/mailboxes, mailboxId, pageSize, totalRequired, field selection, Mailbox status agentNotes: permissions: - Email mailbox management scopes: - 'email.mailbox:read' rateLimit: >- Rate-limited per credential per window. Go to /docs/api-users/rate-limits for current values. idempotent: true destructive: false failureRecovery: Read-only. Safe to retry. related: apis: - title: Email API — Mailboxes href: /docs/references/rest/email/list-mailboxes guides: - title: Provision a mailbox href: /docs/api-users/email/mailboxes/provision-mailboxes concepts: - title: About the Email API href: /docs/api-users/email - title: Authentication href: /docs/api-users/auth - title: Handle errors href: /docs/api-users/errors --- ## Overview This guide covers listing mailboxes across the domains an account owns, filtering and paginating the results, and looking up a single mailbox by ID. `GET /v1/email/mailboxes` returns all mailboxes across account-owned domains in a single paginated response. Use `page` and `pageSize` to navigate; follow the `next` and `prev` links in the response rather than constructing URLs. Filter by `status`, select specific fields with `field`, or add `totalRequired=true` to include total counts. Requesting counts costs an extra query, so leave it off unless the caller needs it. `GET /v1/email/mailboxes/{mailboxId}` returns a single mailbox by ID. Go to [List mailboxes](https://developer.godaddy.com/docs/references/rest/email/list-mailboxes) for all available query parameters and response schemas. ## Prerequisites The following prerequisites are required before you can list and look up mailboxes. * a [PAT](https://developer.godaddy.com/docs/api-users/auth) with `email.mailbox:read` scope ## List mailboxes `GET /v1/email/mailboxes` returns mailboxes across all domains the authenticated account owns, in a single unified view. The following procedure lists mailboxes. * List mailboxes: ```bash tab="curl" curl -s "https://api.godaddy.com/v1/email/mailboxes" \ -H "Authorization: Bearer $GODADDY_PAT" ``` ```js tab="Node" const res = await fetch("https://api.godaddy.com/v1/email/mailboxes", { headers: { Authorization: `Bearer ${process.env.GODADDY_PAT}` }, }); const mailboxes = await res.json(); ``` ```python tab="Python" import os, requests res = requests.get( "https://api.godaddy.com/v1/email/mailboxes", headers={"Authorization": f"Bearer {os.environ['GODADDY_PAT']}"}, ) mailboxes = res.json() ``` ```go tab="Go" package main import ( "net/http" "os" ) func listMailboxes() (*http.Response, error) { req, _ := http.NewRequest("GET", "https://api.godaddy.com/v1/email/mailboxes", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT")) return http.DefaultClient.Do(req) } ``` ### Filter by status `status` filters the list to mailboxes in a single state. This is useful for finding mailboxes still provisioning or ones that failed. The following procedure filters mailboxes by status. * Filter by status: ```bash tab="curl" curl -s "https://api.godaddy.com/v1/email/mailboxes?status=FAILED" \ -H "Authorization: Bearer $GODADDY_PAT" ``` ```js tab="Node" const status = "FAILED"; const res = await fetch( `https://api.godaddy.com/v1/email/mailboxes?status=${status}`, { headers: { Authorization: `Bearer ${process.env.GODADDY_PAT}` } } ); const mailboxes = await res.json(); ``` ```python tab="Python" import os, requests status = "FAILED" res = requests.get( "https://api.godaddy.com/v1/email/mailboxes", params={"status": status}, headers={"Authorization": f"Bearer {os.environ['GODADDY_PAT']}"}, ) mailboxes = res.json() ``` ```go tab="Go" package main import ( "net/http" "os" ) func listByStatus(status string) (*http.Response, error) { req, _ := http.NewRequest("GET", "https://api.godaddy.com/v1/email/mailboxes?status="+status, nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT")) return http.DefaultClient.Do(req) } ``` ### Select specific fields `field` returns only the top-level `Mailbox` fields you name. Omitting it returns all fields. The following procedure requests specific fields. * Select fields: ```bash tab="curl" curl -s "https://api.godaddy.com/v1/email/mailboxes?field=mailboxId,emailAddress,status" \ -H "Authorization: Bearer $GODADDY_PAT" ``` ```js tab="Node" const fields = "mailboxId,emailAddress,status"; const res = await fetch( `https://api.godaddy.com/v1/email/mailboxes?field=${fields}`, { headers: { Authorization: `Bearer ${process.env.GODADDY_PAT}` } } ); const mailboxes = await res.json(); ``` ```python tab="Python" import os, requests fields = "mailboxId,emailAddress,status" res = requests.get( "https://api.godaddy.com/v1/email/mailboxes", params={"field": fields}, headers={"Authorization": f"Bearer {os.environ['GODADDY_PAT']}"}, ) mailboxes = res.json() ``` ```go tab="Go" package main import ( "net/http" "os" ) func listFields(fields string) (*http.Response, error) { req, _ := http.NewRequest("GET", "https://api.godaddy.com/v1/email/mailboxes?field="+fields, nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT")) return http.DefaultClient.Do(req) } ``` ### Get total counts `totalRequired=true` adds `totalItems` and `totalPages` to the response and a `last` link for jumping to the final page. The following procedure requests total counts. * Get total counts: ```bash tab="curl" curl -s "https://api.godaddy.com/v1/email/mailboxes?totalRequired=true" \ -H "Authorization: Bearer $GODADDY_PAT" ``` ```js tab="Node" const res = await fetch( "https://api.godaddy.com/v1/email/mailboxes?totalRequired=true", { headers: { Authorization: `Bearer ${process.env.GODADDY_PAT}` } } ); const mailboxes = await res.json(); ``` ```python tab="Python" import os, requests res = requests.get( "https://api.godaddy.com/v1/email/mailboxes", params={"totalRequired": "true"}, headers={"Authorization": f"Bearer {os.environ['GODADDY_PAT']}"}, ) mailboxes = res.json() ``` ```go tab="Go" package main import ( "net/http" "os" ) func listWithCounts() (*http.Response, error) { req, _ := http.NewRequest("GET", "https://api.godaddy.com/v1/email/mailboxes?totalRequired=true", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT")) return http.DefaultClient.Do(req) } ``` ## Get a single mailbox `GET /v1/email/mailboxes/{mailboxId}` returns one mailbox by ID. Go to [Provision a mailbox](https://developer.godaddy.com/docs/api-users/email/mailboxes/provision-mailboxes) for the polling procedure after mailbox creation. The following procedure gets a single mailbox by ID. * Get the mailbox: ```bash tab="curl" curl -s "https://api.godaddy.com/v1/email/mailboxes/$MAILBOX_ID" \ -H "Authorization: Bearer $GODADDY_PAT" ``` ```js tab="Node" const res = await fetch( `https://api.godaddy.com/v1/email/mailboxes/${process.env.MAILBOX_ID}`, { headers: { Authorization: `Bearer ${process.env.GODADDY_PAT}` } } ); const mailbox = await res.json(); ``` ```python tab="Python" import os, requests res = requests.get( f"https://api.godaddy.com/v1/email/mailboxes/{os.environ['MAILBOX_ID']}", headers={"Authorization": f"Bearer {os.environ['GODADDY_PAT']}"}, ) mailbox = res.json() ``` ```go tab="Go" package main import ( "net/http" "os" ) func getMailbox(mailboxID string) (*http.Response, error) { req, _ := http.NewRequest("GET", "https://api.godaddy.com/v1/email/mailboxes/"+mailboxID, nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT")) return http.DefaultClient.Do(req) } ``` ## Example responses ### List mailboxes `GET /v1/email/mailboxes` returns a paginated `items` array with `links` for navigation: ```json { "items": [ { "mailboxId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "emailAddress": "jane.smith@example.com", "mailboxType": "TITAN", "status": "COMPLETED", "links": [...] } ], "links": [ { "rel": "self", "href": "/v1/email/mailboxes?page=1&pageSize=25" }, { "rel": "next", "href": "/v1/email/mailboxes?page=2&pageSize=25" } ] } ``` When `totalRequired=true`, the response also includes `totalItems`, `totalPages`, and a `last` link: ```json { "items": [ { "mailboxId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "emailAddress": "jane.smith@example.com", "mailboxType": "TITAN", "status": "COMPLETED" } ], "totalItems": 100, "totalPages": 4, "links": [ { "rel": "self", "href": "/v1/email/mailboxes?page=1&pageSize=25" }, { "rel": "next", "href": "/v1/email/mailboxes?page=2&pageSize=25" }, { "rel": "last", "href": "/v1/email/mailboxes?page=4&pageSize=25" } ] } ``` ### Get a single mailbox `GET /v1/email/mailboxes/{mailboxId}` returns the full `Mailbox` object: ```json { "mailboxId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "emailAddress": "jane.smith@example.com", "mailboxType": "TITAN", "firstName": "Jane", "lastName": "Smith", "displayName": "Jane Smith", "status": "COMPLETED", "createdAt": "2024-03-15T10:30:00Z", "updatedAt": "2024-06-01T08:00:00Z", "links": [ { "rel": "self", "href": "/v1/email/mailboxes/a1b2c3d4-e5f6-7890-abcd-ef1234567890" } ] } ``` ## Common errors The following table lists common errors and recommended actions: | Status | Most likely cause | Recommended action | | ------ | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | | `400` | Invalid query parameter (for example, `pageSize` above `100`, or an unknown `field` name). | Inspect `details[]` in the error response. | | `403` | Credential lacks `email.mailbox:read` scope. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) to check required scopes. | | `404` | `mailboxId` doesn't exist or isn't visible to this caller. | Verify the `mailboxId`. | | `429` | Rate limit exceeded. | Wait, then retry. Go to [Handle rate limits](https://developer.godaddy.com/docs/api-users/rate-limits) for current limits and handling guidance. | Go to [Handle errors](https://developer.godaddy.com/docs/api-users/errors) for the full error envelope. # How to provision a mailbox (https://developer.godaddy.com/en/docs/api-users/email/mailboxes/provision-mailboxes) --- title: How to provision a mailbox description: >- Check eligibility, create a mailbox, and poll until it's ready, using the GoDaddy Email API. keywords: >- create mailbox, check-mailbox-eligibility, POST /v1/email/mailboxes, Idempotency-Key, mailbox provisioning, Titan email, EXECUTING COMPLETED FAILED, eligibleAccounts agentNotes: permissions: - Email mailbox management scopes: - 'email.mailbox:read' - 'email.mailbox:create' rateLimit: >- Rate-limited per credential per window. Go to /docs/api-users/rate-limits for current values. idempotent: true destructive: false failureRecovery: >- POST /mailboxes requires an Idempotency-Key header. Retrying with the same key returns the original response instead of creating a duplicate mailbox. related: apis: - title: Email API — Mailboxes href: /docs/references/rest/email/create-mailbox guides: - title: List and look up mailboxes href: /docs/api-users/email/mailboxes/manage-mailboxes concepts: - title: About the Email API href: /docs/api-users/email - title: Authentication href: /docs/api-users/auth - title: Handle errors href: /docs/api-users/errors --- ## Overview This guide covers provisioning a mailbox using the GoDaddy Email API. Start with an eligibility check. `GET /v1/email/check-mailbox-eligibility` tells you whether the address can be provisioned and which entitlements are available. Some entitlements carry requirements the caller must consent to before provisioning (like a free-trial auto-renewal agreement); if those are present, include matching `consents` in the create request. Go to [Create mailbox](https://developer.godaddy.com/docs/references/rest/email/create-mailbox) for the full request body schema including `consents`. Mailbox creation is asynchronous. `POST /v1/email/mailboxes` accepts the configuration and returns `202 Accepted` immediately, then provisions the mailbox in the background. Include an `Idempotency-Key` header on every create request so that retrying a failed call returns the original response instead of creating a duplicate. After creation, poll `GET /v1/email/mailboxes/{mailboxId}` until `status` reaches `COMPLETED` or `FAILED`. Go to [About the Email API](https://developer.godaddy.com/docs/api-users/email#how-mailbox-creation-works) for the status flow diagram. ## Prerequisites The following prerequisites are required before you can provision a mailbox. * a [PAT](https://developer.godaddy.com/docs/api-users/auth) with `email.mailbox:create` scope * an email address on a domain the authenticated account owns ## Provision a mailbox The following procedure provisions a mailbox. 1. Check whether the email address is eligible: ```bash tab="curl" curl -s "https://api.godaddy.com/v1/email/check-mailbox-eligibility?email=$EMAIL_ADDRESS" \ -H "Authorization: Bearer $GODADDY_PAT" ``` ```js tab="Node" const res = await fetch( `https://api.godaddy.com/v1/email/check-mailbox-eligibility?email=${encodeURIComponent(process.env.EMAIL_ADDRESS)}`, { headers: { Authorization: `Bearer ${process.env.GODADDY_PAT}` } } ); const eligibility = await res.json(); ``` ```python tab="Python" import os, requests res = requests.get( "https://api.godaddy.com/v1/email/check-mailbox-eligibility", params={"email": os.environ["EMAIL_ADDRESS"]}, headers={"Authorization": f"Bearer {os.environ['GODADDY_PAT']}"}, ) eligibility = res.json() ``` ```go tab="Go" package main import ( "net/http" "net/url" "os" ) func checkEligibility() (*http.Response, error) { u := "https://api.godaddy.com/v1/email/check-mailbox-eligibility?" + url.Values{"email": {os.Getenv("EMAIL_ADDRESS")}}.Encode() req, _ := http.NewRequest("GET", u, nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT")) return http.DefaultClient.Do(req) } ``` If the eligibility check returns `422`, the address is not eligible for provisioning. Check `details[]` in the response body for the reason (for example, `EMAIL_PLAN_NOT_AVAILABLE`). Don't attempt to create the mailbox. 2. Create the mailbox: ```bash tab="curl" curl -s -X POST "https://api.godaddy.com/v1/email/mailboxes" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d "{ \"emailAddress\": \"$EMAIL_ADDRESS\", \"accountId\": \"$ACCOUNT_ID\", \"firstName\": \"$FIRST_NAME\", \"lastName\": \"$LAST_NAME\", \"consents\": [{ \"type\": \"FREETRIAL_AUTORENEW\" }] }" ``` ```js tab="Node" const res = await fetch("https://api.godaddy.com/v1/email/mailboxes", { method: "POST", headers: { Authorization: `Bearer ${process.env.GODADDY_PAT}`, "Idempotency-Key": crypto.randomUUID(), "Content-Type": "application/json", }, body: JSON.stringify({ emailAddress: process.env.EMAIL_ADDRESS, accountId: process.env.ACCOUNT_ID, firstName: process.env.FIRST_NAME, lastName: process.env.LAST_NAME, consents: [{ type: "FREETRIAL_AUTORENEW" }], }), }); const mailbox = await res.json(); ``` ```python tab="Python" import os, uuid, requests res = requests.post( "https://api.godaddy.com/v1/email/mailboxes", headers={ "Authorization": f"Bearer {os.environ['GODADDY_PAT']}", "Idempotency-Key": str(uuid.uuid4()), }, json={ "emailAddress": os.environ["EMAIL_ADDRESS"], "accountId": os.environ["ACCOUNT_ID"], "firstName": os.environ["FIRST_NAME"], "lastName": os.environ["LAST_NAME"], "consents": [{"type": "FREETRIAL_AUTORENEW"}], }, ) mailbox = res.json() ``` ```go tab="Go" package main import ( "bytes" "encoding/json" "net/http" "os" "github.com/google/uuid" ) func createMailbox() (*http.Response, error) { body, _ := json.Marshal(map[string]any{ "emailAddress": os.Getenv("EMAIL_ADDRESS"), "accountId": os.Getenv("ACCOUNT_ID"), "firstName": os.Getenv("FIRST_NAME"), "lastName": os.Getenv("LAST_NAME"), "consents": []map[string]string{{"type": "FREETRIAL_AUTORENEW"}}, }) req, _ := http.NewRequest("POST", "https://api.godaddy.com/v1/email/mailboxes", bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT")) req.Header.Set("Idempotency-Key", uuid.NewString()) req.Header.Set("Content-Type", "application/json") return http.DefaultClient.Do(req) } ``` 3. Poll for completion: ```bash tab="curl" curl -s "https://api.godaddy.com/v1/email/mailboxes/$MAILBOX_ID" \ -H "Authorization: Bearer $GODADDY_PAT" ``` ```js tab="Node" async function pollMailbox(mailboxId, intervalMs = 3000) { while (true) { const res = await fetch( `https://api.godaddy.com/v1/email/mailboxes/${mailboxId}`, { headers: { Authorization: `Bearer ${process.env.GODADDY_PAT}` } } ); const mailbox = await res.json(); if (mailbox.status === "COMPLETED") return mailbox; if (mailbox.status === "FAILED") throw new Error("Mailbox provisioning failed"); await new Promise((r) => setTimeout(r, intervalMs)); } } ``` ```python tab="Python" import os, time, requests def poll_mailbox(mailbox_id, interval=3): while True: res = requests.get( f"https://api.godaddy.com/v1/email/mailboxes/{mailbox_id}", headers={"Authorization": f"Bearer {os.environ['GODADDY_PAT']}"}, ) mailbox = res.json() if mailbox["status"] == "COMPLETED": return mailbox if mailbox["status"] == "FAILED": raise RuntimeError("Mailbox provisioning failed") time.sleep(interval) ``` ```go tab="Go" package main import ( "encoding/json" "fmt" "net/http" "os" "time" ) func pollMailbox(mailboxID string) { for { req, _ := http.NewRequest("GET", "https://api.godaddy.com/v1/email/mailboxes/"+mailboxID, nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT")) res, _ := http.DefaultClient.Do(req) var mailbox struct { Status string `json:"status"` } json.NewDecoder(res.Body).Decode(&mailbox) res.Body.Close() switch mailbox.Status { case "COMPLETED": fmt.Println("Mailbox ready") return case "FAILED": panic("Mailbox provisioning failed") } time.Sleep(3 * time.Second) } } ``` ## Example responses The following sections provide example responses for the mailbox provisioning API. ### Check eligibility `GET /v1/email/check-mailbox-eligibility` returns an `EligibilityResult`: ```json { "isEligible": true, "eligibleAccounts": [ { "accountId": "00000000-0000-0000-0000-000000000001", "mailboxType": "TITAN", "accountName": "Professional Email", "default": true, "requirements": [] } ] } ``` ### Create a mailbox `POST /v1/email/mailboxes` returns the new `Mailbox` object: ```json { "mailboxId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "emailAddress": "jane.smith@example.com", "mailboxType": "TITAN", "firstName": "Jane", "lastName": "Smith", "displayName": "Jane Smith", "status": "EXECUTING", "agreements": [ { "type": "FREETRIAL_AUTORENEW", "agreed": true } ], "createdAt": "2024-06-15T12:00:00Z", "updatedAt": "2024-06-15T12:00:00Z", "links": [ { "rel": "self", "href": "/mailboxes/a1b2c3d4-e5f6-7890-abcd-ef1234567890" } ] } ``` The response includes a `Location` header pointing at the new mailbox resource. The `agreements` field reflects the `consents` submitted in the request body. ## Common errors The following table lists common errors and recommended actions: | Status | Most likely cause | Recommended action | | ------ | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | `400` | Malformed request body, missing required field, or invalid `email` query parameter. | Inspect `details[]` in the error response. | | `403` | Credential lacks the required scope, or the domain isn't owned by the authenticated account. | Check `name` in the error response to distinguish. | | `404` | `mailboxId` doesn't exist or isn't visible to this caller. | Verify the `mailboxId` from the create response. | | `409` | A mailbox already exists for the requested email address on this domain. | Look up the existing mailbox instead of creating a new one. | | `422` | No available entitlements for the domain, or an unsupported domain type. | Run the eligibility check before retrying. | | `429` | Rate limit exceeded. | Wait, then retry. Go to [Handle rate limits](https://developer.godaddy.com/docs/api-users/rate-limits) for current limits and handling guidance. | Go to [Handle errors](https://developer.godaddy.com/docs/api-users/errors) for the full error envelope. # How to deploy your Node.js app (https://developer.godaddy.com/en/docs/api-users/hosting/workflows/deploy-nodejs-app) --- title: How to deploy your Node.js app description: >- Deploy your app end to end — create an app, attach a hosting plan, upload code, publish, and verify it's running. keywords: >- POST /v1/hosting/apps, GET /app-operations, operation status, POST /apps/{appId}/imports, import upload, PUT /apps/{appId}/subscription, POST /apps/{appId}/deployments, deployment status, async polling pattern agentNotes: scopes: - 'hosting.application:create' - 'hosting.application:read' - 'hosting.source:write' - 'hosting.deployment:execute' - 'hosting.subscription:write' rateLimit: 10–120 req/min per client IP depending on operation failureRecovery: >- Every write in this walkthrough is async. Poll the status endpoint for each step until it reaches a terminal state. related: concepts: - title: Hosting core concepts href: /docs/api-users/hosting/concepts - title: Node.js app requirements href: /docs/api-users/hosting/app-requirements guides: - title: Manage apps href: /docs/api-users/hosting/manage-apps - title: Attach to a hosting plan href: /docs/api-users/hosting/attach-hosting-plan - title: Attach domain href: /docs/api-users/hosting/attach-domain apis: - title: Hosting API reference href: /docs/references/rest/hosting --- ## Overview This walkthrough deploys an app from scratch. By the end, you'll have a running app on the `publish` variant. Every write operation is async. The API returns a operation or deployment id immediately, and you poll until the operation completes. All code blocks use `$BASE_URL` for the API gateway host and `$GODADDY_PAT` for your Personal Access Token. Go to [Hosting core concepts](https://developer.godaddy.com/docs/api-users/hosting/concepts#scopes-reference) for the scopes you need. ## Prerequisites The following prerequisites are required before you can deploy your Node.js app: * a [Personal Access Token](https://developer.godaddy.com/personal-access-token) with the following scopes: `hosting.application:create`, `hosting.application:read`, `hosting.source:write`, `hosting.deployment:execute`, `hosting.subscription:write` * a zipped Node.js application that meets the [Node.js app requirements](https://developer.godaddy.com/docs/api-users/hosting/app-requirements) * a web hosting subscription to attach the app to ## Deploy your app The following procedure creates an app, uploads source, attaches it to a hosting plan, publishes it to production, and confirms the app is running. ### Create an app `POST /apps?appType=NODEJS` accepts a name and returns `202 Accepted` with an `AppOperation`, including a `links[rel=self]` URL. Poll that URL with `GET /app-operations/{operationId}` until the status reaches `COMPLETED` (success) or `FAILED`. 1. Create the app: ```bash tab="curl" curl -s -X POST "$BASE_URL/v1/hosting/apps?appType=NODEJS" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "Content-Type: application/json" \ -d '{ "name": "my-first-app" }' ``` ```js tab="Node" const res = await fetch(`${process.env.BASE_URL}/v1/hosting/apps?appType=NODEJS`, { method: 'POST', headers: { Authorization: `Bearer ${process.env.GODADDY_PAT}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ name: 'my-first-app' }), }); const { operationId, links } = await res.json(); const pollUrl = links.find(l => l.rel === 'self').href; ``` ```python tab="Python" import requests, os resp = requests.post( f"{os.environ['BASE_URL']}/v1/hosting/apps?appType=NODEJS", headers={"Authorization": f"Bearer {os.environ['GODADDY_PAT']}"}, json={"name": "my-first-app"}, ) data = resp.json() operation_id = data["operationId"] poll_url = next(l["href"] for l in data["links"] if l["rel"] == "self") ``` ```go tab="Go" body := strings.NewReader(`{"name":"my-first-app"}`) req, _ := http.NewRequest("POST", os.Getenv("BASE_URL")+"/v1/hosting/apps?appType=NODEJS", body) req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT")) req.Header.Set("Content-Type", "application/json") resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() var result map[string]interface{} json.NewDecoder(resp.Body).Decode(&result) operationId := result["operationId"].(string) // Find poll URL from links array where rel == "self" ``` 2. Poll until the operation reaches `COMPLETED` or `FAILED`: ```bash tab="curl" curl -s "$BASE_URL/v1/hosting/app-operations/$OPERATION_ID" \ -H "Authorization: Bearer $GODADDY_PAT" | jq '{status: .status, appId: .app.id}' ``` ```js tab="Node" let data; do { await new Promise(r => setTimeout(r, 3000)); const r = await fetch(pollUrl, { headers: { Authorization: `Bearer ${process.env.GODADDY_PAT}` }, }); data = await r.json(); } while (data.status !== 'COMPLETED' && data.status !== 'FAILED'); const appId = data.app.id; ``` ```python tab="Python" import time while True: r = requests.get( poll_url, headers={"Authorization": f"Bearer {os.environ['GODADDY_PAT']}"}, ) data = r.json() if data["status"] in ("COMPLETED", "FAILED"): break time.sleep(3) app_id = data["app"]["id"] ``` ```go tab="Go" var appID string for { req, _ := http.NewRequest("GET", pollUrl, nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT")) resp, _ := http.DefaultClient.Do(req) var result map[string]interface{} json.NewDecoder(resp.Body).Decode(&result) resp.Body.Close() status := result["status"].(string) if status == "COMPLETED" || status == "FAILED" { app := result["app"].(map[string]interface{}) appID = app["id"].(string) break } time.Sleep(3 * time.Second) } ``` ### Upload source and preview your app `POST /apps/{appId}/imports` accepts a zip as `multipart/form-data` and returns `202 Accepted` with a `SourceImport` operation. Poll it with `GET /apps/{appId}/imports/{importId}` until the status reaches `COMPLETED` or `FAILED`. 1. Upload the zip: ```bash tab="curl" curl -s -X POST "$BASE_URL/v1/hosting/apps/$APP_ID/imports" \ -H "Authorization: Bearer $GODADDY_PAT" \ -F "file=@./my-app.zip" ``` ```js tab="Node" import { createReadStream } from 'fs'; import FormData from 'form-data'; const form = new FormData(); form.append('file', createReadStream('./my-app.zip')); const res = await fetch(`${process.env.BASE_URL}/v1/hosting/apps/${appId}/imports`, { method: 'POST', headers: { Authorization: `Bearer ${process.env.GODADDY_PAT}`, ...form.getHeaders(), }, body: form, }); const { importId, links } = await res.json(); const pollUrl = links.find(l => l.rel === 'self').href; ``` ```python tab="Python" with open('./my-app.zip', 'rb') as f: resp = requests.post( f"{os.environ['BASE_URL']}/v1/hosting/apps/{app_id}/imports", headers={"Authorization": f"Bearer {os.environ['GODADDY_PAT']}"}, files={"file": f}, ) data = resp.json() import_id = data["importId"] poll_url = next(l["href"] for l in data["links"] if l["rel"] == "self") ``` ```go tab="Go" file, _ := os.Open("./my-app.zip") defer file.Close() buf := &bytes.Buffer{} w := multipart.NewWriter(buf) part, _ := w.CreateFormFile("file", "my-app.zip") io.Copy(part, file) w.Close() req, _ := http.NewRequest("POST", os.Getenv("BASE_URL")+"/v1/hosting/apps/"+appID+"/imports", buf) req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT")) req.Header.Set("Content-Type", w.FormDataContentType()) resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() var result map[string]interface{} json.NewDecoder(resp.Body).Decode(&result) importId := result["importId"].(string) // Find poll URL from links array where rel == "self" ``` 2. Poll until the upload reaches a terminal state: ```bash tab="curl" curl -s "$BASE_URL/v1/hosting/apps/$APP_ID/imports/$IMPORT_ID" \ -H "Authorization: Bearer $GODADDY_PAT" | jq .status ``` ```js tab="Node" let importStatus; do { await new Promise(r => setTimeout(r, 2000)); const r = await fetch(pollUrl, { headers: { Authorization: `Bearer ${process.env.GODADDY_PAT}` }, }); ({ status: importStatus } = await r.json()); } while (importStatus !== 'COMPLETED' && importStatus !== 'FAILED'); ``` ```python tab="Python" while True: r = requests.get( poll_url, headers={"Authorization": f"Bearer {os.environ['GODADDY_PAT']}"}, ) import_status = r.json()["status"] if import_status in ("COMPLETED", "FAILED"): break time.sleep(2) ``` ```go tab="Go" for { req, _ := http.NewRequest("GET", pollUrl, nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT")) resp, _ := http.DefaultClient.Do(req) var result map[string]interface{} json.NewDecoder(resp.Body).Decode(&result) resp.Body.Close() if s := result["status"].(string); s == "COMPLETED" || s == "FAILED" { break } time.Sleep(2 * time.Second) } ``` ### Attach to hosting plan This step is required before going live for Node.js apps. Future product types may have different provisioning requirements. Before you can publish a Node.js app, you must attach it to a web hosting subscription. Use a valid subscription ID from your GoDaddy account (`GET /subscriptions?hostingProduct=WEB_HOSTING` lists the plans on it). `PUT /apps/{appId}/subscription` attaches the app to one, and the call is synchronous, so there's no operation to poll. Go to [Attach to a hosting plan](https://developer.godaddy.com/docs/api-users/hosting/attach-hosting-plan) for detailed guidance. * Attach the app to a subscription: ```bash tab="curl" curl -s -X PUT "$BASE_URL/v1/hosting/apps/$APP_ID/subscription" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "Content-Type: application/json" \ -d '{ "subscriptionId": "'$SUBSCRIPTION_ID'" }' ``` ```js tab="Node" const res = await fetch(`${process.env.BASE_URL}/v1/hosting/apps/${appId}/subscription`, { method: 'PUT', headers: { Authorization: `Bearer ${process.env.GODADDY_PAT}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ subscriptionId }), }); if (!res.ok) { console.error(`Error: ${res.status}`); return; } const result = await res.json(); ``` ```python tab="Python" import requests, os resp = requests.put( f"{os.environ['BASE_URL']}/v1/hosting/apps/{app_id}/subscription", headers={"Authorization": f"Bearer {os.environ['GODADDY_PAT']}"}, json={"subscriptionId": subscription_id}, ) if resp.status_code != 200: print(f"Error: {resp.status_code}") exit(1) result = resp.json() ``` ```go tab="Go" body := strings.NewReader(`{"subscriptionId":"` + subscriptionID + `"}`) req, _ := http.NewRequest("PUT", os.Getenv("BASE_URL")+"/v1/hosting/apps/"+appID+"/subscription", body) req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT")) req.Header.Set("Content-Type", "application/json") resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() if resp.StatusCode != 200 { fmt.Printf("Error: %d\n", resp.StatusCode) return } var result map[string]interface{} json.NewDecoder(resp.Body).Decode(&result) ``` ### Publish your app `POST /apps/{appId}/deployments` builds the latest source, deploys it to the publish environment, and returns `202 Accepted` with a `Deployment`. Poll it with `GET /apps/{appId}/deployments/{deploymentId}` until the status reaches `COMPLETED` or `FAILED`. 1. Publish the app: ```bash tab="curl" curl -s -X POST "$BASE_URL/v1/hosting/apps/$APP_ID/deployments" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "Content-Type: application/json" \ -d '{}' ``` ```js tab="Node" const res = await fetch(`${process.env.BASE_URL}/v1/hosting/apps/${appId}/deployments`, { method: 'POST', headers: { Authorization: `Bearer ${process.env.GODADDY_PAT}`, 'Content-Type': 'application/json', }, body: JSON.stringify({}), }); const { deploymentId, links } = await res.json(); const pollUrl = links.find(l => l.rel === 'self').href; ``` ```python tab="Python" resp = requests.post( f"{os.environ['BASE_URL']}/v1/hosting/apps/{app_id}/deployments", headers={"Authorization": f"Bearer {os.environ['GODADDY_PAT']}"}, json={}, ) data = resp.json() deployment_id = data["deploymentId"] poll_url = next(l["href"] for l in data["links"] if l["rel"] == "self") ``` ```go tab="Go" req, _ := http.NewRequest("POST", os.Getenv("BASE_URL")+"/v1/hosting/apps/"+appID+"/deployments", strings.NewReader(`{}`)) req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT")) req.Header.Set("Content-Type", "application/json") resp, _ := http.DefaultClient.Do(req) var result map[string]interface{} json.NewDecoder(resp.Body).Decode(&result) deploymentId := result["deploymentId"].(string) // Find poll URL from links array where rel == "self" ``` 2. Poll until deployment reaches a terminal state: ```bash tab="curl" curl -s "$BASE_URL/v1/hosting/apps/$APP_ID/deployments/$DEPLOYMENT_ID" \ -H "Authorization: Bearer $GODADDY_PAT" | jq .status ``` ```js tab="Node" let deploymentStatus; do { await new Promise(r => setTimeout(r, 5000)); const r = await fetch(pollUrl, { headers: { Authorization: `Bearer ${process.env.GODADDY_PAT}` }, }); ({ status: deploymentStatus } = await r.json()); } while (deploymentStatus !== 'COMPLETED' && deploymentStatus !== 'FAILED'); ``` ```python tab="Python" while True: r = requests.get( poll_url, headers={"Authorization": f"Bearer {os.environ['GODADDY_PAT']}"}, ) deployment_status = r.json()["status"] if deployment_status in ("COMPLETED", "FAILED"): break time.sleep(5) ``` ```go tab="Go" for { req, _ := http.NewRequest("GET", pollUrl, nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT")) resp, _ := http.DefaultClient.Do(req) var result map[string]interface{} json.NewDecoder(resp.Body).Decode(&result) resp.Body.Close() if s := result["status"].(string); s == "COMPLETED" || s == "FAILED" { break } time.Sleep(5 * time.Second) } ``` ### Verify `GET /apps/{appId}/status` returns the application lifecycle in top-level `status` and per-environment detail in `variants`. Inspect the `PUBLISH` entry in `variants` to confirm that environment is up. * Read the app status: ```bash tab="curl" curl -s "$BASE_URL/v1/hosting/apps/$APP_ID/status" \ -H "Authorization: Bearer $GODADDY_PAT" | jq . ``` ```js tab="Node" const r = await fetch(`${process.env.BASE_URL}/v1/hosting/apps/${appId}/status`, { headers: { Authorization: `Bearer ${process.env.GODADDY_PAT}` }, }); console.log(await r.json()); ``` ```python tab="Python" resp = requests.get( f"{os.environ['BASE_URL']}/v1/hosting/apps/{app_id}/status", headers={"Authorization": f"Bearer {os.environ['GODADDY_PAT']}"}, ) print(resp.json()) ``` ```go tab="Go" req, _ := http.NewRequest("GET", os.Getenv("BASE_URL")+"/v1/hosting/apps/"+appID+"/status", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT")) resp, _ := http.DefaultClient.Do(req) io.Copy(os.Stdout, resp.Body) resp.Body.Close() ``` ### Get app URLs `GET /apps/{appId}` returns the full app record, including a `urls` object with the URL for each environment. Your code is not live at `urls.publish` until you publish. * Read the app record to get its URLs: ```bash tab="curl" curl -s "$BASE_URL/v1/hosting/apps/$APP_ID" \ -H "Authorization: Bearer $GODADDY_PAT" | jq .urls ``` ```js tab="Node" const res = await fetch(`${process.env.BASE_URL}/v1/hosting/apps/${appId}`, { headers: { Authorization: `Bearer ${process.env.GODADDY_PAT}` }, }); const { urls } = await res.json(); console.log(urls.preview); // preview environment URL console.log(urls.publish); // publish environment URL ``` ```python tab="Python" resp = requests.get( f"{os.environ['BASE_URL']}/v1/hosting/apps/{app_id}", headers={"Authorization": f"Bearer {os.environ['GODADDY_PAT']}"}, ) urls = resp.json()["urls"] print(urls["preview"]) # preview environment URL print(urls["publish"]) # publish environment URL ``` ```go tab="Go" req, _ := http.NewRequest("GET", os.Getenv("BASE_URL")+"/v1/hosting/apps/"+appID, nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT")) resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() var result map[string]interface{} json.NewDecoder(resp.Body).Decode(&result) urls := result["urls"].(map[string]interface{}) fmt.Println(urls["preview"]) // preview environment URL fmt.Println(urls["publish"]) // publish environment URL ``` ## Deploy updates To deploy new code to an existing app, repeat the upload and publish steps. You don't need to create a new app or re-attach it to a hosting plan. 1. Upload the updated zip using `POST /apps/{appId}/imports`. Go to [Upload source and preview your app](#upload-source-and-preview-your-app) for the full procedure. 2. Publish the update using `POST /apps/{appId}/deployments`. Go to [Publish your app](#publish-your-app) for the full procedure. ## Common errors The following table lists common errors and recommended actions: | Status | Cause | Action | | ---------------------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------- | | `401` | Expired or revoked PAT, or missing scope | Go to [Hosting core concepts](https://developer.godaddy.com/docs/api-users/hosting/concepts#scopes-reference) for the scopes you need | | `429` | Rate limit exceeded | Back off and retry. Go to [Rate limits](https://developer.godaddy.com/docs/api-users/rate-limits) for handling guidance | | Operation stuck in `PENDING` | Upstream provisioning delay | Wait up to two minutes before treating it as failed | | Import job `FAILED` | Malformed zip or build failure | Check the application structure and reupload | # Create a checkout and place an order (https://developer.godaddy.com/en/docs/api-users/shopping/guides/purchase) --- title: Create a checkout and place an order description: >- Create a checkout session with selected products, update it with buyer and payment details, complete the checkout, and retrieve the resulting order. keywords: >- checkout session, POST /checkout-sessions, PUT /checkout-sessions, complete checkout, GET /orders, line_items, payment instrument, shopping.checkout:execute, shopping.order:read, order retrieval agentNotes: permissions: - Shopping Checkout - Shopping Orders scopes: - 'shopping.checkout:execute' - 'shopping.order:read' rateLimit: >- Rate-limited per credential. Go to /docs/api-users/rate-limits for current values. idempotent: false destructive: true failureRecovery: >- Completion charges the selected instrument. Poll GET /orders/:orderId until the order becomes visible. related: guides: - title: About the Shopping API href: /docs/api-users/shopping - title: Search the catalog href: /docs/api-users/shopping/guides/search-catalog concepts: - title: Handle errors href: /docs/api-users/errors - title: Rate limits href: /docs/api-users/rate-limits apis: - title: Shopping Checkout reference href: /docs/references/rest/shopping/create-checkout - title: Shopping Orders reference href: /docs/references/rest/shopping/get-order --- ## Overview Use this Shopping API v1 workflow to create a checkout, select payment, accept agreements, complete the checkout session to place the order, and retrieve its details. A checkout session moves through states (`incomplete` → `ready_for_complete` → `completed`) as you add required data. All write operations require `shopping.checkout:execute` scope. Order retrieval requires `shopping.order:read` scope. Go to [About the Shopping API](https://developer.godaddy.com/docs/api-users/shopping) for required headers and the checkout state machine. ## Prerequisites The following prerequisites are required before you can create a checkout and place an order: * at least one variant ID from the product catalog * a PAT with `shopping.checkout:execute` and `shopping.order:read` scopes * an eligible saved payment instrument on the GoDaddy account * `jq` and `uuidgen` for the curl examples Go to [Search the catalog](https://developer.godaddy.com/docs/api-users/shopping/guides/search-catalog) to get a variant ID. ## Authenticate These examples use a `$GODADDY_PAT` with `shopping.checkout:execute` and `shopping.order:read` scopes. Go to [About the Shopping API](https://developer.godaddy.com/docs/api-users/shopping#authentication) for the full list of required scopes. ## Create a checkout session `POST /v1/shopping/checkout-sessions` creates a checkout session with one or more line items. Pass variant IDs from the catalog search results. The following procedure creates a checkout session. * Create a session with a selected variant: ```bash tab="curl" export CREATE_IDEMPOTENCY_KEY="$(uuidgen)" CREATE_RESPONSE="$(curl --fail-with-body --silent --show-error -X POST "https://api.godaddy.com/v1/shopping/checkout-sessions" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "Request-Id: $(uuidgen)" \ -H "Idempotency-Key: $CREATE_IDEMPOTENCY_KEY" \ -H "Content-Type: application/json" \ -d "$(jq -n --arg id "$VARIANT_ID" '{context:{currency:"USD"},line_items:[{item:{id:$id},quantity:1}]}')")" export SESSION_ID="$(jq -er '.id' <<<"$CREATE_RESPONSE")" export LINE_ITEM_ID="$(jq -er '.line_items[0].id' <<<"$CREATE_RESPONSE")" export PAYMENT_INSTRUMENT_ID="$(jq -er '.payment.instruments | (map(select(.selected == true))[0] // .[0]).id' <<<"$CREATE_RESPONSE")" export PAYMENT_HANDLER_ID="$(jq -er '.payment.instruments | (map(select(.selected == true))[0] // .[0]).handler_id' <<<"$CREATE_RESPONSE")" export PAYMENT_INSTRUMENT_TYPE="$(jq -er '.payment.instruments | (map(select(.selected == true))[0] // .[0]).type' <<<"$CREATE_RESPONSE")" ``` ```js tab="Node" const checkoutId = crypto.randomUUID(); const res = await fetch("https://api.godaddy.com/v1/shopping/checkout-sessions", { method: "POST", headers: { Authorization: `Bearer ${process.env.GODADDY_PAT}`, "Request-Id": crypto.randomUUID(), "Idempotency-Key": checkoutId, "Content-Type": "application/json", }, body: JSON.stringify({ context: { currency: "USD" }, line_items: [{ item: { id: process.env.VARIANT_ID }, quantity: 1 }], }), }); const checkout = await res.json(); if (!res.ok || checkout.ucp?.status === "error") throw new Error(checkout.messages?.[0]?.code ?? `HTTP ${res.status}`); const sessionId = checkout.id; const lineItem = checkout.line_items[0]; const writableLineItem = { id: lineItem.id, item: { id: lineItem.item.id }, quantity: lineItem.quantity, ...(lineItem.input ? { input: lineItem.input } : {}), }; const paymentInstrument = checkout.payment?.instruments?.find((item) => item.selected) ?? checkout.payment?.instruments?.[0]; if (!paymentInstrument) throw new Error("No eligible saved payment instrument"); ``` ```python tab="Python" import os, uuid, requests idem_key = str(uuid.uuid4()) res = requests.post( "https://api.godaddy.com/v1/shopping/checkout-sessions", headers={ "Authorization": f"Bearer {os.environ['GODADDY_PAT']}", "Request-Id": str(uuid.uuid4()), "Idempotency-Key": idem_key, }, json={ "context": {"currency": "USD"}, "line_items": [{"item": {"id": os.environ["VARIANT_ID"]}, "quantity": 1}], }, ) checkout = res.json() if not res.ok or checkout.get("ucp", {}).get("status") == "error": raise RuntimeError(checkout.get("messages", [{}])[0].get("code", f"HTTP {res.status_code}")) session_id = checkout.get("id") line_item = checkout["line_items"][0] writable_line_item = { "id": line_item["id"], "item": {"id": line_item["item"]["id"]}, "quantity": line_item["quantity"], **({"input": line_item["input"]} if line_item.get("input") else {}), } payment_instrument = next( (item for item in checkout.get("payment", {}).get("instruments", []) if item.get("selected")), next(iter(checkout.get("payment", {}).get("instruments", [])), None), ) if not payment_instrument: raise RuntimeError("No eligible saved payment instrument") ``` ```go tab="Go" package main import ( "bytes" "crypto/rand" "encoding/json" "fmt" "log" "net/http" "os" ) func requestID() string { value := make([]byte, 16) if _, err := rand.Read(value); err != nil { log.Fatal(err) } value[6], value[8] = (value[6]&0x0f)|0x40, (value[8]&0x3f)|0x80 return fmt.Sprintf("%x-%x-%x-%x-%x", value[:4], value[4:6], value[6:8], value[8:10], value[10:]) } func main() { body, _ := json.Marshal(map[string]any{ "context": map[string]string{"currency": "USD"}, "line_items": []map[string]any{ {"item": map[string]string{"id": os.Getenv("VARIANT_ID")}, "quantity": 1}, }, }) req, _ := http.NewRequest("POST", "https://api.godaddy.com/v1/shopping/checkout-sessions", bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT")) req.Header.Set("Request-Id", requestID()) req.Header.Set("Idempotency-Key", os.Getenv("CREATE_IDEMPOTENCY_KEY")) req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() if res.StatusCode != http.StatusCreated { log.Fatalf("create checkout returned %s", res.Status) } var checkout map[string]any json.NewDecoder(res.Body).Decode(&checkout) fmt.Println("session:", checkout["id"], "status:", checkout["status"]) } ``` The response includes an `id` and initial `status`. Save the writable line items and returned payment instruments for later requests. Go to [Example responses](#example-responses) for trimmed response examples. Always send a unique `Idempotency-Key` on `POST /checkout-sessions`. If the request times out, retry the unchanged request with the same key. The server returns the existing session instead of creating a duplicate. A status of `incomplete` means required fields are missing. A status of `ready_for_complete` means all required fields are present. Check `messages[]` in the response for specific missing-field details. ## Review the checkout `GET /v1/shopping/checkout-sessions/{id}` returns current line items, totals, saved payment instruments, messages, links, and required agreements. The following procedure refreshes the checkout before an update or completion. * Retrieve the checkout and selected payment instrument: ```bash tab="curl" CHECKOUT_RESPONSE="$(curl --fail-with-body --silent --show-error \ "https://api.godaddy.com/v1/shopping/checkout-sessions/$SESSION_ID" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "Request-Id: $(uuidgen)")" export PAYMENT_INSTRUMENT_ID="$(jq -er '.payment.instruments | (map(select(.selected == true))[0] // .[0]).id' <<<"$CHECKOUT_RESPONSE")" export PAYMENT_HANDLER_ID="$(jq -er '.payment.instruments | (map(select(.selected == true))[0] // .[0]).handler_id' <<<"$CHECKOUT_RESPONSE")" export PAYMENT_INSTRUMENT_TYPE="$(jq -er '.payment.instruments | (map(select(.selected == true))[0] // .[0]).type' <<<"$CHECKOUT_RESPONSE")" ``` ```js tab="Node" const checkoutRes = await fetch( `https://api.godaddy.com/v1/shopping/checkout-sessions/${sessionId}`, { headers: { Authorization: `Bearer ${process.env.GODADDY_PAT}`, "Request-Id": crypto.randomUUID() } }, ); const currentCheckout = await checkoutRes.json(); if (!checkoutRes.ok || currentCheckout.ucp?.status === "error") { throw new Error(currentCheckout.messages?.[0]?.code ?? `HTTP ${checkoutRes.status}`); } const selectedInstrument = currentCheckout.payment?.instruments?.find((item) => item.selected) ?? currentCheckout.payment?.instruments?.[0]; if (!selectedInstrument) throw new Error("No eligible saved payment instrument"); ``` ```python tab="Python" checkout_res = requests.get( f"https://api.godaddy.com/v1/shopping/checkout-sessions/{session_id}", headers={ "Authorization": f"Bearer {os.environ['GODADDY_PAT']}", "Request-Id": str(uuid.uuid4()), }, ) current_checkout = checkout_res.json() if not checkout_res.ok or current_checkout.get("ucp", {}).get("status") == "error": raise RuntimeError(current_checkout.get("messages", [{}])[0].get("code", f"HTTP {checkout_res.status_code}")) instruments = current_checkout.get("payment", {}).get("instruments", []) payment_instrument = next((item for item in instruments if item.get("selected")), instruments[0] if instruments else None) if not payment_instrument: raise RuntimeError("No eligible saved payment instrument") ``` ```go tab="Go" package main import ( "crypto/rand" "encoding/json" "fmt" "log" "net/http" "os" ) func requestID() string { value := make([]byte, 16) if _, err := rand.Read(value); err != nil { log.Fatal(err) } value[6], value[8] = (value[6]&0x0f)|0x40, (value[8]&0x3f)|0x80 return fmt.Sprintf("%x-%x-%x-%x-%x", value[:4], value[4:6], value[6:8], value[8:10], value[10:]) } func main() { req, _ := http.NewRequest("GET", "https://api.godaddy.com/v1/shopping/checkout-sessions/"+os.Getenv("SESSION_ID"), nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT")) req.Header.Set("Request-Id", requestID()) res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() if res.StatusCode != http.StatusOK { log.Fatalf("get checkout returned %s", res.Status) } var checkout map[string]any if err := json.NewDecoder(res.Body).Decode(&checkout); err != nil { log.Fatal(err) } } ``` Persist the checkout ID, writable line item, and selected instrument for later requests. Preserve the instrument's returned `id`, `handler_id`, and `type`. The standalone Go examples read these values from `SESSION_ID`, `LINE_ITEM_ID`, `PAYMENT_INSTRUMENT_ID`, `PAYMENT_HANDLER_ID`, and `PAYMENT_INSTRUMENT_TYPE`. ## Update the checkout `PUT /v1/shopping/checkout-sessions/{id}` replaces the writable checkout state. Use it to select a saved payment instrument and resend all line items. `PUT` is a full replace, not a merge. Include the complete `line_items[]` array and every product `input` on each update. Omitting a writable field clears its previous value. Payment instruments must already exist on the GoDaddy account. If none is eligible, add one at [GoDaddy payment methods](https://account.godaddy.com/payment-methods/add-payment) and retrieve the checkout again. Set `BUYER_FIRST_NAME`, `BUYER_LAST_NAME`, `BUYER_EMAIL`, and `BUYER_PHONE` to the buyer's contact values before running the examples. The following procedure selects a payment instrument. * Select a payment instrument and resend all line items: ```bash tab="curl" export UPDATE_IDEMPOTENCY_KEY="$(uuidgen)" UPDATE_RESPONSE="$(curl --fail-with-body --silent --show-error -X PUT "https://api.godaddy.com/v1/shopping/checkout-sessions/$SESSION_ID" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "Request-Id: $(uuidgen)" \ -H "Idempotency-Key: $UPDATE_IDEMPOTENCY_KEY" \ -H "Content-Type: application/json" \ -d "$(jq -n \ --arg line_id "$LINE_ITEM_ID" --arg variant_id "$VARIANT_ID" \ --arg first "$BUYER_FIRST_NAME" --arg last "$BUYER_LAST_NAME" \ --arg email "$BUYER_EMAIL" --arg phone "$BUYER_PHONE" \ --arg instrument_id "$PAYMENT_INSTRUMENT_ID" --arg handler "$PAYMENT_HANDLER_ID" \ --arg type "$PAYMENT_INSTRUMENT_TYPE" \ '{context:{currency:"USD"},line_items:[{id:$line_id,item:{id:$variant_id},quantity:1}],buyer:{first_name:$first,last_name:$last,email:$email,phone_number:$phone},payment:{instruments:[{id:$instrument_id,handler_id:$handler,type:$type,selected:true}]}}')")" ``` ```js tab="Node" const updateIdempotencyKey = crypto.randomUUID(); const res = await fetch( `https://api.godaddy.com/v1/shopping/checkout-sessions/${sessionId}`, { method: "PUT", headers: { Authorization: `Bearer ${process.env.GODADDY_PAT}`, "Request-Id": crypto.randomUUID(), "Idempotency-Key": updateIdempotencyKey, "Content-Type": "application/json", }, body: JSON.stringify({ context: { currency: "USD" }, line_items: [writableLineItem], buyer: { first_name: process.env.BUYER_FIRST_NAME, last_name: process.env.BUYER_LAST_NAME, email: process.env.BUYER_EMAIL, phone_number: process.env.BUYER_PHONE, }, payment: { instruments: [ { ...selectedInstrument, selected: true, }, ], }, }), } ); const updated = await res.json(); if (!res.ok || updated.ucp?.status === "error") throw new Error(updated.messages?.[0]?.code ?? `HTTP ${res.status}`); ``` ```python tab="Python" import os, uuid, requests idem_key = str(uuid.uuid4()) res = requests.put( f"https://api.godaddy.com/v1/shopping/checkout-sessions/{session_id}", headers={ "Authorization": f"Bearer {os.environ['GODADDY_PAT']}", "Request-Id": str(uuid.uuid4()), "Idempotency-Key": idem_key, }, json={ "context": {"currency": "USD"}, "line_items": [writable_line_item], "buyer": { "first_name": os.environ["BUYER_FIRST_NAME"], "last_name": os.environ["BUYER_LAST_NAME"], "email": os.environ["BUYER_EMAIL"], "phone_number": os.environ["BUYER_PHONE"], }, "payment": { "instruments": [ {**payment_instrument, "selected": True} ] }, }, ) updated = res.json() if not res.ok or updated.get("ucp", {}).get("status") == "error": raise RuntimeError(updated.get("messages", [{}])[0].get("code", f"HTTP {res.status_code}")) ``` ```go tab="Go" package main import ( "bytes" "crypto/rand" "encoding/json" "fmt" "log" "net/http" "os" ) func requestID() string { value := make([]byte, 16) if _, err := rand.Read(value); err != nil { log.Fatal(err) } value[6], value[8] = (value[6]&0x0f)|0x40, (value[8]&0x3f)|0x80 return fmt.Sprintf("%x-%x-%x-%x-%x", value[:4], value[4:6], value[6:8], value[8:10], value[10:]) } func main() { sessionID := os.Getenv("SESSION_ID") body, _ := json.Marshal(map[string]any{ "context": map[string]string{"currency": "USD"}, "line_items": []map[string]any{ {"id": os.Getenv("LINE_ITEM_ID"), "item": map[string]string{"id": os.Getenv("VARIANT_ID")}, "quantity": 1}, }, "buyer": map[string]string{ "first_name": os.Getenv("BUYER_FIRST_NAME"), "last_name": os.Getenv("BUYER_LAST_NAME"), "email": os.Getenv("BUYER_EMAIL"), "phone_number": os.Getenv("BUYER_PHONE"), }, "payment": map[string]any{ "instruments": []map[string]any{ { "id": os.Getenv("PAYMENT_INSTRUMENT_ID"), "handler_id": os.Getenv("PAYMENT_HANDLER_ID"), "type": os.Getenv("PAYMENT_INSTRUMENT_TYPE"), "selected": true, }, }, }, }) req, _ := http.NewRequest("PUT", "https://api.godaddy.com/v1/shopping/checkout-sessions/"+sessionID, bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT")) req.Header.Set("Request-Id", requestID()) req.Header.Set("Idempotency-Key", os.Getenv("UPDATE_IDEMPOTENCY_KEY")) req.Header.Set("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() if res.StatusCode != http.StatusOK { log.Fatalf("update checkout returned %s", res.Status) } var updated map[string]any json.NewDecoder(res.Body).Decode(&updated) fmt.Println("status:", updated["status"]) } ``` After the update, check `status`: * If `ready_for_complete`, proceed to complete the checkout. * If `incomplete`, check `messages[]` for remaining required fields. * If `required_agreements[]` is present, include `consent` when completing. If an item can't be priced at update time, the server removes it from `line_items[]` and attaches a `messages[]` entry with `code: line_item_removed`. Check for missing items before proceeding. ## Configure products and fulfillment Include one `line_items[]` entry for each selected variant. Set `quantity` for each entry and preserve its returned line-item `id` on updates. Some variants expose an `input_schema`. Build `line_items[].input` from that schema and resend the input on every PUT request. | Data | Request location | | ----------------------- | ------------------------------------------------------------------------------ | | Buyer contact | `buyer.first_name`, `buyer.last_name`, `buyer.email`, and `buyer.phone_number` | | Product configuration | `line_items[].input` | | Shipping or pickup | `fulfillment.methods[]` and its selected destination | | Billing address | `payment.instruments[].billing_address` | | Saved payment selection | The returned instrument `id`, `handler_id`, `type`, and `selected: true` | Do not assume every saved instrument is a card. Preserve the handler and type returned by the checkout. Go to [Shopping Checkout reference](https://developer.godaddy.com/docs/references/rest/shopping/create-checkout) for the full input, fulfillment, payment, and address schemas. ## Handle required agreements Before completing, check the checkout response for `required_agreements[]`. Some purchases require the buyer to accept terms first. Before completing: * Include each agreement with `required: true` in `consent.agreement_types`. * Record the buyer's acceptance time in `agreed_at`. Missing or incomplete consent returns HTTP `400` with `validation_error`. Example `required_agreements[]` in a checkout response: ```json { "required_agreements": [ { "key": "api_services_purchase_agreement", "title": "API Services Purchase Agreement", "url": "https://www.godaddy.com/legal/agreements/api-services-purchase-agreement", "required": true } ] } ``` ## Complete the checkout `POST /v1/shopping/checkout-sessions/{id}/complete` completes a `ready_for_complete` session and creates its order. The request body must include `payment`. Include `consent` if the checkout has `required_agreements[]`. The following procedure completes the checkout. * Complete the session: ```bash tab="curl" export COMPLETE_IDEMPOTENCY_KEY="$(uuidgen)" export AGREED_AT="$(date -u +%Y-%m-%dT%H:%M:%SZ)" REQUIRED_AGREEMENTS="$(jq -c '[.required_agreements[]? | select(.required == true) | .key]' <<<"$UPDATE_RESPONSE")" COMPLETE_BODY="$(jq -n \ --arg instrument_id "$PAYMENT_INSTRUMENT_ID" --arg handler "$PAYMENT_HANDLER_ID" \ --arg type "$PAYMENT_INSTRUMENT_TYPE" --argjson agreements "$REQUIRED_AGREEMENTS" \ --arg agreed_at "$AGREED_AT" \ '{payment:{instruments:[{id:$instrument_id,handler_id:$handler,type:$type,selected:true}]}} + (if ($agreements | length) > 0 then {consent:{agreement_types:$agreements,agreed_at:$agreed_at}} else {} end)')" COMPLETE_RESPONSE="$(curl --fail-with-body --silent --show-error -X POST "https://api.godaddy.com/v1/shopping/checkout-sessions/$SESSION_ID/complete" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "Request-Id: $(uuidgen)" \ -H "Idempotency-Key: $COMPLETE_IDEMPOTENCY_KEY" \ -H "Content-Type: application/json" \ -d "$COMPLETE_BODY")" export ORDER_ID="$(jq -er '.order.id' <<<"$COMPLETE_RESPONSE")" ``` ```js tab="Node" const completionIdempotencyKey = crypto.randomUUID(); const requiredAgreementKeys = (updated.required_agreements ?? []) .filter((agreement) => agreement.required) .map((agreement) => agreement.key); const res = await fetch( `https://api.godaddy.com/v1/shopping/checkout-sessions/${sessionId}/complete`, { method: "POST", headers: { Authorization: `Bearer ${process.env.GODADDY_PAT}`, "Request-Id": crypto.randomUUID(), "Idempotency-Key": completionIdempotencyKey, "Content-Type": "application/json", }, body: JSON.stringify({ payment: { instruments: [{ ...selectedInstrument, selected: true }] }, ...(requiredAgreementKeys.length > 0 ? { consent: { agreement_types: requiredAgreementKeys, agreed_at: new Date().toISOString() } } : {}), }), } ); const result = await res.json(); if (!res.ok || result.ucp?.status === "error") throw new Error(result.messages?.[0]?.code ?? `HTTP ${res.status}`); const orderId = result.order?.id; const receiptUrl = result.order?.permalink_url; ``` ```python tab="Python" import os, uuid, requests from datetime import datetime, timezone completion_idempotency_key = str(uuid.uuid4()) required_agreement_keys = [ agreement["key"] for agreement in updated.get("required_agreements", []) if agreement.get("required") is True ] complete_body = { "payment": {"instruments": [{**payment_instrument, "selected": True}]}, } if required_agreement_keys: complete_body["consent"] = { "agreement_types": required_agreement_keys, "agreed_at": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"), } res = requests.post( f"https://api.godaddy.com/v1/shopping/checkout-sessions/{session_id}/complete", headers={ "Authorization": f"Bearer {os.environ['GODADDY_PAT']}", "Request-Id": str(uuid.uuid4()), "Idempotency-Key": completion_idempotency_key, }, json=complete_body, ) result = res.json() if not res.ok or result.get("ucp", {}).get("status") == "error": raise RuntimeError(result.get("messages", [{}])[0].get("code", f"HTTP {res.status_code}")) order_id = result.get("order", {}).get("id") receipt_url = result.get("order", {}).get("permalink_url") ``` ```go tab="Go" package main import ( "bytes" "crypto/rand" "encoding/json" "fmt" "log" "net/http" "os" "time" ) func requestID() string { value := make([]byte, 16) if _, err := rand.Read(value); err != nil { log.Fatal(err) } value[6], value[8] = (value[6]&0x0f)|0x40, (value[8]&0x3f)|0x80 return fmt.Sprintf("%x-%x-%x-%x-%x", value[:4], value[4:6], value[6:8], value[8:10], value[10:]) } func main() { sessionID := os.Getenv("SESSION_ID") var agreementTypes []string _ = json.Unmarshal([]byte(os.Getenv("REQUIRED_AGREEMENTS_JSON")), &agreementTypes) requestBody := map[string]any{ "payment": map[string]any{"instruments": []map[string]any{{ "id": os.Getenv("PAYMENT_INSTRUMENT_ID"), "handler_id": os.Getenv("PAYMENT_HANDLER_ID"), "type": os.Getenv("PAYMENT_INSTRUMENT_TYPE"), "selected": true, }}}, } if len(agreementTypes) > 0 { requestBody["consent"] = map[string]any{"agreement_types": agreementTypes, "agreed_at": time.Now().UTC().Format(time.RFC3339)} } body, _ := json.Marshal(requestBody) req, _ := http.NewRequest("POST", "https://api.godaddy.com/v1/shopping/checkout-sessions/"+sessionID+"/complete", bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT")) req.Header.Set("Request-Id", requestID()) req.Header.Set("Idempotency-Key", os.Getenv("COMPLETE_IDEMPOTENCY_KEY")) req.Header.Set("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() if res.StatusCode != http.StatusOK { log.Fatalf("complete checkout returned %s", res.Status) } var result map[string]any json.NewDecoder(res.Body).Decode(&result) if order, ok := result["order"].(map[string]any); ok { fmt.Println("order:", order["id"], "receipt:", order["permalink_url"]) } } ``` The completion examples build `consent` from the checkout's required agreements. Never hardcode agreement keys across products. The standalone Go completion example reads the required agreement-key array from `REQUIRED_AGREEMENTS_JSON` and the retry-stable key from `COMPLETE_IDEMPOTENCY_KEY`. ```json { "payment": { "instruments": [{ "id": "$PAYMENT_INSTRUMENT_ID", "handler_id": "$PAYMENT_HANDLER_ID", "type": "$PAYMENT_INSTRUMENT_TYPE", "selected": true }] }, "consent": { "agreement_types": ["api_services_purchase_agreement"], "agreed_at": "$AGREED_AT" } } ``` When `status` is `completed`, `order.id` contains the order identifier and `order.permalink_url` links to the receipt. ## Retrieve the order `GET /v1/shopping/orders/{id}` returns order totals, line statuses, fulfillment data, and a receipt link. A new order might return `404 order_not_found` while the read model updates. The following procedure retrieves an order. * Get order detail: ```bash tab="curl" ORDER_FILE="$(mktemp)" delay=1 for attempt in 1 2 3 4 5 6; do status="$(curl --silent --show-error -o "$ORDER_FILE" -w '%{http_code}' \ "https://api.godaddy.com/v1/shopping/orders/$ORDER_ID" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "Request-Id: $(uuidgen)")" if [ "$status" = "200" ]; then break; fi code="$(jq -r '.messages[0].code // empty' "$ORDER_FILE")" if [ "$status" != "404" ] || [ "$code" != "order_not_found" ]; then jq . "$ORDER_FILE" >&2 exit 1 fi sleep "$delay" delay=$((delay < 4 ? delay * 2 : 4)) done test "$status" = "200" ORDER_RESPONSE="$(cat "$ORDER_FILE")" rm -f "$ORDER_FILE" ``` ```js tab="Node" let delay = 1000; let order; for (let attempt = 1; attempt <= 6; attempt++) { const res = await fetch(`https://api.godaddy.com/v1/shopping/orders/${orderId}`, { headers: { Authorization: `Bearer ${process.env.GODADDY_PAT}`, "Request-Id": crypto.randomUUID() }, }); const body = await res.json(); if (res.ok) { order = body; break; } if (res.status !== 404 || body.messages?.[0]?.code !== "order_not_found" || attempt === 6) { throw new Error(body.messages?.[0]?.code ?? `HTTP ${res.status}`); } await new Promise((resolve) => setTimeout(resolve, delay)); delay = Math.min(delay * 2, 4000); } ``` ```python tab="Python" import os, time, uuid, requests delay = 1 for attempt in range(1, 7): res = requests.get( f"https://api.godaddy.com/v1/shopping/orders/{order_id}", headers={ "Authorization": f"Bearer {os.environ['GODADDY_PAT']}", "Request-Id": str(uuid.uuid4()), }, ) order = res.json() if res.ok: break code = order.get("messages", [{}])[0].get("code") if res.status_code != 404 or code != "order_not_found" or attempt == 6: raise RuntimeError(code or f"HTTP {res.status_code}") time.sleep(delay) delay = min(delay * 2, 4) ``` ```go tab="Go" package main import ( "crypto/rand" "encoding/json" "fmt" "log" "net/http" "os" "time" ) func requestID() string { value := make([]byte, 16) if _, err := rand.Read(value); err != nil { log.Fatal(err) } value[6], value[8] = (value[6]&0x0f)|0x40, (value[8]&0x3f)|0x80 return fmt.Sprintf("%x-%x-%x-%x-%x", value[:4], value[4:6], value[6:8], value[8:10], value[10:]) } func main() { orderID := os.Getenv("ORDER_ID") delay := time.Second for attempt := 1; attempt <= 6; attempt++ { req, _ := http.NewRequest("GET", "https://api.godaddy.com/v1/shopping/orders/"+orderID, nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT")) req.Header.Set("Request-Id", requestID()) res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } var body map[string]any if err := json.NewDecoder(res.Body).Decode(&body); err != nil { log.Fatal(err) } res.Body.Close() if res.StatusCode == http.StatusOK { fmt.Println(body); return } code := "" if messages, ok := body["messages"].([]any); ok && len(messages) > 0 { if message, ok := messages[0].(map[string]any); ok { code, _ = message["code"].(string) } } if res.StatusCode != http.StatusNotFound || code != "order_not_found" || attempt == 6 { log.Fatalf("get order returned %s (%s)", res.Status, code) } time.Sleep(delay) if delay < 4*time.Second { delay *= 2 } } } ``` ## Example responses The following sections provide example responses for creating and completing checkout sessions. Amounts use ISO 4217 minor units. For USD, an amount of `999` represents `$9.99`. ### Checkout session `POST /checkout-sessions` returns `201` with a session object. An eligible saved instrument can make it immediately `ready_for_complete`: ```json { "id": "d9cf79e3-b39b-4e58-8f30-ddfe1619e969", "status": "ready_for_complete", "currency": "USD", "line_items": [ { "id": "1", "item": { "id": "hosting-economyapi:1mo" }, "quantity": 1, "totals": [ { "type": "subtotal", "amount": 999 }, { "type": "total", "amount": 999 } ] } ], "totals": [ { "type": "subtotal", "amount": 999 }, { "type": "total", "amount": 999 } ], "payment": { "instruments": [ { "id": "payment-instrument-id", "handler_id": "com.godaddy.payments", "type": "card", "selected": true } ] }, "required_agreements": [ { "key": "universal_terms_and_conditions", "title": "Universal Terms of Service Agreement", "required": true, "url": "https://www.godaddy.com/legal/agreements/universal-terms-of-service-agreement" } ], "ucp": { "version": "2026-04-08" } } ``` ### Completed checkout `POST /checkout-sessions/{id}/complete` returns `status: completed` when payment succeeds. Use the numeric `order.id` to retrieve the order: ```json { "id": "d9cf79e3-b39b-4e58-8f30-ddfe1619e969", "status": "completed", "order": { "id": "2211390786", "permalink_url": "https://account.godaddy.com/receipts/view/2211390786" }, "ucp": { "version": "2026-04-08" } } ``` ## Common errors | Response | `messages[].code` | Cause | Action | | ------------------ | -------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | | `200` with warning | `line_item_removed` | A line item could not be priced and was removed from the session. | Re-check `line_items[]` before completion. | | `400` | `payment_instrument_invalid` | The selected payment profile is unavailable or ineligible. | Retrieve the checkout and select an eligible instrument. | | `400` | `validation_error` | `POST /complete` was called with missing or incomplete `consent.agreement_types`. | Check the checkout's `required_agreements[]`, collect buyer consent, and retry with `consent` included. | | `401` | — | The PAT is missing, invalid, or expired. | Generate or export a valid PAT. | | `403` | — | The PAT lacks the required Shopping scope. | Generate a PAT with `shopping.checkout:execute` and `shopping.order:read`. | | `422` | `item_not_found`, `invalid_domain`, `invalid_term`, `unsupported_currency` | The request is valid JSON but cannot be processed. | Correct the item or currency before retrying with a new idempotency key. | | `404` | `order_not_found` | A completed order is not visible in the read model yet. | Retry the unchanged GET with bounded backoff. | | `429` | — | Rate limit exceeded. | Wait for the `Retry-After` header value, then retry. | After completion, `GET /checkout-sessions/{id}` might return `404 checkout_not_found`. Keep the completion response and use its `order.id` for order retrieval. Go to [About the Shopping API](https://developer.godaddy.com/docs/api-users/shopping#error-responses) for error handling. ## Verify the purchase Confirm that completion returned `status: completed` and a numeric `order.id`. After the order becomes visible, verify its currency, total, line-item statuses, and receipt permalink. Fulfillment `events[]` and `expectations[]` are optional. Process them when present; do not require one expectation per line item. # Search the catalog (https://developer.godaddy.com/en/docs/api-users/shopping/guides/search-catalog) --- title: Search the catalog description: >- Search for GoDaddy products, look up variants by ID, and retrieve product detail using the Shopping API. keywords: >- catalog search, product lookup, POST /catalog/search, POST /catalog/lookup, POST /catalog/product, product variants, hosting search agentNotes: permissions: - Shopping Catalog scopes: - 'shopping.catalog:read' rateLimit: >- Rate-limited per credential. Go to /docs/api-users/rate-limits for current values. idempotent: true destructive: false failureRecovery: >- All catalog operations are safe to retry. Use a new Request-Id on each retry. related: guides: - title: About the Shopping API href: /docs/api-users/shopping - 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 --- ## 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](https://developer.godaddy.com/docs/api-users/shopping) 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](https://developer.godaddy.com/docs/api-users/shopping#authentication) 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: ```bash tab="curl" 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 } }' ``` ```js tab="Node" const res = await fetch("https://api.godaddy.com/v1/shopping/catalog/search", { method: "POST", headers: { Authorization: `Bearer ${process.env.GODADDY_PAT}`, "Request-Id": crypto.randomUUID(), "Content-Type": "application/json", }, body: JSON.stringify({ context: { address_country: "US", currency: "USD", language: "en" }, pagination: { limit: 20 }, }), }); const data = await res.json(); if (!res.ok || data.ucp?.status === "error") throw new Error(data.messages?.[0]?.code ?? `HTTP ${res.status}`); const { products, pagination } = data; ``` ```python tab="Python" import os, uuid, requests res = requests.post( "https://api.godaddy.com/v1/shopping/catalog/search", headers={ "Authorization": f"Bearer {os.environ['GODADDY_PAT']}", "Request-Id": str(uuid.uuid4()), }, json={ "context": {"address_country": "US", "currency": "USD", "language": "en"}, "pagination": {"limit": 20}, }, ) data = res.json() if not res.ok or data.get("ucp", {}).get("status") == "error": raise RuntimeError(data.get("messages", [{}])[0].get("code", f"HTTP {res.status_code}")) products = data.get("products", []) ``` ```go tab="Go" package main import ( "bytes" "crypto/rand" "encoding/json" "fmt" "log" "net/http" "os" ) func requestID() string { value := make([]byte, 16) if _, err := rand.Read(value); err != nil { log.Fatal(err) } value[6], value[8] = (value[6]&0x0f)|0x40, (value[8]&0x3f)|0x80 return fmt.Sprintf("%x-%x-%x-%x-%x", value[:4], value[4:6], value[6:8], value[8:10], value[10:]) } func main() { body, _ := json.Marshal(map[string]any{ "context": map[string]string{"address_country": "US", "currency": "USD", "language": "en"}, "pagination": map[string]int{"limit": 20}, }) req, _ := http.NewRequest("POST", "https://api.godaddy.com/v1/shopping/catalog/search", bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT")) req.Header.Set("Request-Id", requestID()) req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() if res.StatusCode != http.StatusOK { log.Fatalf("catalog search returned %s", res.Status) } var data map[string]any json.NewDecoder(res.Body).Decode(&data) fmt.Println(data["products"]) } ``` * Search for hosting products by keyword: ```bash tab="curl" 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 } }' ``` ```js tab="Node" const res = await fetch("https://api.godaddy.com/v1/shopping/catalog/search", { method: "POST", headers: { Authorization: `Bearer ${process.env.GODADDY_PAT}`, "Request-Id": crypto.randomUUID(), "Content-Type": "application/json", }, body: JSON.stringify({ query: "hosting", context: { address_country: "US", currency: "USD", language: "en" }, pagination: { limit: 20 }, }), }); const data = await res.json(); if (!res.ok || data.ucp?.status === "error") throw new Error(data.messages?.[0]?.code ?? `HTTP ${res.status}`); const { products, pagination } = data; ``` ```python tab="Python" import os, uuid, requests res = requests.post( "https://api.godaddy.com/v1/shopping/catalog/search", headers={ "Authorization": f"Bearer {os.environ['GODADDY_PAT']}", "Request-Id": str(uuid.uuid4()), }, json={ "query": "hosting", "context": {"address_country": "US", "currency": "USD", "language": "en"}, "pagination": {"limit": 20}, }, ) data = res.json() if not res.ok or data.get("ucp", {}).get("status") == "error": raise RuntimeError(data.get("messages", [{}])[0].get("code", f"HTTP {res.status_code}")) products = data.get("products", []) ``` ```go tab="Go" package main import ( "bytes" "crypto/rand" "encoding/json" "fmt" "log" "net/http" "os" ) func requestID() string { value := make([]byte, 16) if _, err := rand.Read(value); err != nil { log.Fatal(err) } value[6], value[8] = (value[6]&0x0f)|0x40, (value[8]&0x3f)|0x80 return fmt.Sprintf("%x-%x-%x-%x-%x", value[:4], value[4:6], value[6:8], value[8:10], value[10:]) } func main() { body, _ := json.Marshal(map[string]any{ "query": "hosting", "context": map[string]string{"address_country": "US", "currency": "USD", "language": "en"}, "pagination": map[string]int{"limit": 20}, }) req, _ := http.NewRequest("POST", "https://api.godaddy.com/v1/shopping/catalog/search", bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT")) req.Header.Set("Request-Id", requestID()) req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() if res.StatusCode != http.StatusOK { log.Fatalf("catalog search returned %s", res.Status) } var data map[string]any json.NewDecoder(res.Body).Decode(&data) fmt.Println(data["products"]) } ``` 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: ```bash tab="curl" 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"}}')" ``` ```js tab="Node" const res = await fetch("https://api.godaddy.com/v1/shopping/catalog/lookup", { method: "POST", headers: { Authorization: `Bearer ${process.env.GODADDY_PAT}`, "Request-Id": crypto.randomUUID(), "Content-Type": "application/json", }, body: JSON.stringify({ ids: [process.env.VARIANT_ID], context: { address_country: "US", currency: "USD", language: "en" }, }), }); const data = await res.json(); if (!res.ok || data.ucp?.status === "error") throw new Error(data.messages?.[0]?.code ?? `HTTP ${res.status}`); const { products, messages } = data; ``` ```python tab="Python" import os, uuid, requests res = requests.post( "https://api.godaddy.com/v1/shopping/catalog/lookup", headers={ "Authorization": f"Bearer {os.environ['GODADDY_PAT']}", "Request-Id": str(uuid.uuid4()), }, json={ "ids": [os.environ["VARIANT_ID"]], "context": {"address_country": "US", "currency": "USD", "language": "en"}, }, ) data = res.json() if not res.ok or data.get("ucp", {}).get("status") == "error": raise RuntimeError(data.get("messages", [{}])[0].get("code", f"HTTP {res.status_code}")) products = data.get("products", []) ``` ```go tab="Go" package main import ( "bytes" "crypto/rand" "encoding/json" "fmt" "log" "net/http" "os" ) func requestID() string { value := make([]byte, 16) if _, err := rand.Read(value); err != nil { log.Fatal(err) } value[6], value[8] = (value[6]&0x0f)|0x40, (value[8]&0x3f)|0x80 return fmt.Sprintf("%x-%x-%x-%x-%x", value[:4], value[4:6], value[6:8], value[8:10], value[10:]) } func main() { body, _ := json.Marshal(map[string]any{ "ids": []string{os.Getenv("VARIANT_ID")}, "context": map[string]string{"address_country": "US", "currency": "USD", "language": "en"}, }) req, _ := http.NewRequest("POST", "https://api.godaddy.com/v1/shopping/catalog/lookup", bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT")) req.Header.Set("Request-Id", requestID()) req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() if res.StatusCode != http.StatusOK { log.Fatalf("catalog lookup returned %s", res.Status) } var data map[string]any json.NewDecoder(res.Body).Decode(&data) fmt.Println(data["products"]) } ``` 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: ```bash tab="curl" 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"}}')" ``` ```js tab="Node" const res = await fetch("https://api.godaddy.com/v1/shopping/catalog/product", { method: "POST", headers: { Authorization: `Bearer ${process.env.GODADDY_PAT}`, "Request-Id": crypto.randomUUID(), "Content-Type": "application/json", }, body: JSON.stringify({ id: process.env.VARIANT_ID, context: { address_country: "US", currency: "USD", language: "en" }, }), }); const data = await res.json(); if (!res.ok || data.ucp?.status === "error") throw new Error(data.messages?.[0]?.code ?? `HTTP ${res.status}`); const { product } = data; ``` ```python tab="Python" import os, uuid, requests res = requests.post( "https://api.godaddy.com/v1/shopping/catalog/product", headers={ "Authorization": f"Bearer {os.environ['GODADDY_PAT']}", "Request-Id": str(uuid.uuid4()), }, json={ "id": os.environ["VARIANT_ID"], "context": {"address_country": "US", "currency": "USD", "language": "en"}, }, ) data = res.json() if not res.ok or data.get("ucp", {}).get("status") == "error": raise RuntimeError(data.get("messages", [{}])[0].get("code", f"HTTP {res.status_code}")) product = data.get("product") ``` ```go tab="Go" package main import ( "bytes" "crypto/rand" "encoding/json" "fmt" "log" "net/http" "os" ) func requestID() string { value := make([]byte, 16) if _, err := rand.Read(value); err != nil { log.Fatal(err) } value[6], value[8] = (value[6]&0x0f)|0x40, (value[8]&0x3f)|0x80 return fmt.Sprintf("%x-%x-%x-%x-%x", value[:4], value[4:6], value[6:8], value[8:10], value[10:]) } func main() { body, _ := json.Marshal(map[string]any{ "id": os.Getenv("VARIANT_ID"), "context": map[string]string{"address_country": "US", "currency": "USD", "language": "en"}, }) req, _ := http.NewRequest("POST", "https://api.godaddy.com/v1/shopping/catalog/product", bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT")) req.Header.Set("Request-Id", requestID()) req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() if res.StatusCode != http.StatusOK { log.Fatalf("product lookup returned %s", res.Status) } var data map[string]any json.NewDecoder(res.Body).Decode(&data) fmt.Println(data["product"]) } ``` Product detail responses might include `required_agreements[]`. The resolved checkout is authoritative. Go to [Create a checkout and place an order](https://developer.godaddy.com/docs/api-users/shopping/guides/purchase#handle-required-agreements) for the consent flow. ## Interpret catalog results Catalog amounts use ISO 4217 minor units. For USD, an amount of `999` represents `$9.99`. | Field | Use | | -------------------------- | ----------------------------------------------------------------------------------- | | `products[].id` | Identifies the product family. Do not assume this ID is purchasable. | | `products[].variants[].id` | Identifies a purchasable option to send as `line_items[].item.id`. | | `price` and `list_price` | Show the current selling price and optional comparison price. | | `renewal_price` | Shows an optional renewal amount for recurring products. | | `availability.available` | Indicates whether the variant can be purchased. | | `inputs[]` | Correlates lookup results with requested IDs. | | `input_schema` | Defines product-specific configuration to send as `line_items[].input`. | | `included_products[]` | Describes products bundled into a catalog offer. | | `required_agreements[]` | Provides early disclosure; the checkout's resolved agreements remain authoritative. | ## 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](https://developer.godaddy.com/docs/api-users/shopping/guides/purchase) 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: ```json { "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 | Response | `messages[].code` | Cause | Action | | ----------------------- | ---------------------- | -------------------------------------------------- | ---------------------------------------------------------------- | | `200` with info message | `not_found` | A batch lookup could not resolve one requested ID. | Use the returned matches and inspect each informational message. | | `400` | `invalid_request` | A required request field is missing. | Correct the request body. | | `404` | `product_not_found` | Product detail could not resolve the requested ID. | Verify the ID from a catalog search. | | `422` | `unsupported_currency` | The requested currency is not supported. | Use a supported catalog currency. | | `401` | — | The PAT is missing, invalid, or expired. | Generate or export a valid PAT. | | `403` | — | The PAT lacks `shopping.catalog:read`. | Generate a PAT with the required scope. | | `429` | — | Rate limit exceeded. | Wait for the `Retry-After` header value, then retry. | Batch lookup can return HTTP `200` with matches and informational `not_found` messages. Successful responses can omit `ucp.status`. Go to [About the Shopping API](https://developer.godaddy.com/docs/api-users/shopping#error-responses) for error handling. # Create a new abuse ticket (https://developer.godaddy.com/en/docs/references/rest/abuse/create-ticket-v2) --- title: Create a new abuse ticket full: true --- ## POST /v2/abuse/tickets Create a new abuse ticket ### Request body (required) The endpoint which allows the Reporter to create a new abuse ticket Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/AbuseTicketCreate` ### Responses **201** — Success Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/AbuseTicketId` **401** — Authentication info not sent or invalid Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` **422** — Error Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` # Create a new abuse ticket (https://developer.godaddy.com/en/docs/references/rest/abuse/create-ticket) --- title: Create a new abuse ticket full: true --- ## POST /v1/abuse/tickets Create a new abuse ticket ### Request body (required) The endpoint which allows the Reporter to create a new abuse ticket Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/AbuseTicketCreateLegacy` ### Responses **201** — Success Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/AbuseTicketId` **401** — Authentication info not sent or invalid Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` **422** — Error Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` # Retrieve abuse ticket details (https://developer.godaddy.com/en/docs/references/rest/abuse/get-ticket-info-v2) --- title: Retrieve abuse ticket details full: true --- ## GET /v2/abuse/tickets/{ticketId} Retrieve abuse ticket details ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `ticketId` | string | yes | A unique abuse ticket identifier | ### Responses **200** — Success Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/AbuseTicket` **401** — Authentication info not sent or invalid Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` **404** — Invalid ticket id provided Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` # Retrieve abuse ticket details (https://developer.godaddy.com/en/docs/references/rest/abuse/get-ticket-info) --- title: Retrieve abuse ticket details full: true --- ## GET /v1/abuse/tickets/{ticketId} Retrieve abuse ticket details ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `ticketId` | string | yes | A unique abuse ticket identifier | ### Responses **200** — Success Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/AbuseTicketLegacy` **401** — Authentication info not sent or invalid Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` **404** — Invalid ticket id provided Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` # List abuse tickets (https://developer.godaddy.com/en/docs/references/rest/abuse/get-tickets-v2) --- title: List abuse tickets full: true --- ## GET /v2/abuse/tickets List abuse tickets ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `type` | string | no | The type of abuse. | | `closed` | boolean | no | Is this abuse ticket closed? | | `sourceDomainOrIp` | string | no | The domain name or ip address the abuse originated from | | `target` | string | no | The brand/company the abuse is targeting. ie: brand name/bank name | | `createdStart` | string | no | The earliest abuse ticket creation date to pull abuse tickets for | | `createdEnd` | string | no | The latest abuse ticket creation date to pull abuse tickets for | | `limit` | integer | no | Number of abuse ticket numbers to return. | | `offset` | integer | no | The earliest result set record number to pull abuse tickets for | ### Responses **200** — Success Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/AbuseTicketList` **401** — Authentication info not sent or invalid Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` **422** — Error Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` # List abuse tickets (https://developer.godaddy.com/en/docs/references/rest/abuse/get-tickets) --- title: List abuse tickets full: true --- ## GET /v1/abuse/tickets List abuse tickets ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `type` | string | no | The type of abuse. | | `closed` | boolean | no | Is this abuse ticket closed? | | `sourceDomainOrIp` | string | no | The domain name or ip address the abuse originated from | | `target` | string | no | The brand/company the abuse is targeting. ie: brand name/bank name | | `createdStart` | string | no | The earliest abuse ticket creation date to pull abuse tickets for | | `createdEnd` | string | no | The latest abuse ticket creation date to pull abuse tickets for | | `limit` | integer | no | Number of abuse ticket numbers to return. | | `offset` | integer | no | The earliest result set record number to pull abuse tickets for | ### Responses **200** — Success Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/AbuseTicketList` **401** — Authentication info not sent or invalid Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` **422** — Error Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` # Add expiry listings to GoDaddy Auction (https://developer.godaddy.com/en/docs/references/rest/aftermarket/add-expiry-listings) --- title: Add expiry listings to GoDaddy Auction full: true --- ## POST /v1/aftermarket/listings/expiry Add expiry listings to GoDaddy Auction ### Request body (required) An array of expiry listings to be loaded Content-Type: `application/json` Schema: - array - items: Content-Type: `application/xml` Schema: - array - items: Content-Type: `text/xml` Schema: - array - items: ### Responses **200** — Request was successful Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/AftermarketListingAction` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/AftermarketListingAction` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/AftermarketListingAction` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/AftermarketListingAction` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/AftermarketListingAction` **400** — Request was malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **422** — Required parameters must be specified in correct format
Too many Listings provided
Invalid Losing Registrar Id Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` # Remove listings from GoDaddy Auction (https://developer.godaddy.com/en/docs/references/rest/aftermarket/delete-listings) --- title: Remove listings from GoDaddy Auction full: true --- ## DELETE /v1/aftermarket/listings Remove listings from GoDaddy Auction ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `domains` | array | yes | A comma separated list of domain names | ### Responses **200** — Request was successful Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/AftermarketListingAction` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/AftermarketListingAction` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/AftermarketListingAction` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/AftermarketListingAction` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/AftermarketListingAction` **400** — Request was malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **422** — Required parameters must be specified in correct format Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` # List GoDaddy Auction listings (https://developer.godaddy.com/en/docs/references/rest/aftermarket/get-listings) --- title: List GoDaddy Auction listings full: true --- ## GET /v1/customers/{customerId}/auctions/listings List GoDaddy Auction listings ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `customerId` | string | yes | An identifier for a customer. | ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `domains` | string | no | Only include results for the specified domains. Use comma-separated string to include more than one domain. For example, `one.com,two.info,three.biz` | | `listingStatus` | string | no | Only include results for the specified listing status. | | `transferBefore` | string | no | Domain transfer time before this time, ISO 8601, in UTC. Defaults to last day of the previous month if not provided. Applicable only for listings in `FULFILLED` listingStatus. | | `transferAfter` | string | no | Domain transfer time after this time, ISO 8601, in UTC. Defaults to first day of the previous month if not provided. Applicable only for listings in `FULFILLED` listingStatus. | | `limit` | integer | no | Maximum number of items to return. | | `offset` | integer | no | Number of results to skip for pagination. | ### Responses **200** — Request was successful Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Listings` **400** — Request was malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **422** — Required parameters must be specified in correct format Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` # Retrieve legal agreements (https://developer.godaddy.com/en/docs/references/rest/agreements/get) --- title: Retrieve legal agreements full: true --- ## GET /v1/agreements Retrieve legal agreements ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `keys` | array | yes | Keys for Agreements whose details are to be retrieved | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Private-Label-Id` | integer | no | PrivateLabelId to operate as, if different from JWT | | `X-Market-Id` | string | no | Unique identifier of the Market used to retrieve/translate Legal Agreements | ### Responses **200** — Request was successful Content-Type: `application/json` Schema: - array - items: Content-Type: `application/javascript` Schema: - array - items: Content-Type: `application/xml` Schema: - array - items: Content-Type: `text/javascript` Schema: - array - items: Content-Type: `text/xml` Schema: - array - items: **400** — Request was malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` # Cancel pending renewal (https://developer.godaddy.com/en/docs/references/rest/ans/cancel-server-certificate-renewal) --- title: Cancel pending renewal description: Cancels the pending server certificate renewal for this agent. full: true --- Full description Cancels the pending server certificate renewal for this agent. Use when the submitted CSR was incorrect, to switch between CSR and BYOC paths, or to abandon the renewal. Removes the pending renewal and marks any associated CSR as REJECTED. ## DELETE /v1/agents/{agentId}/certificates/server/renewal Cancel pending renewal Cancels the pending server certificate renewal for this agent. Use when the submitted CSR was incorrect, to switch between CSR and BYOC paths, or to abandon the renewal. Removes the pending renewal and marks any associated CSR as REJECTED. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `agentId` | string | yes | Unique identifier of the agent (UUID format) | ### Responses **204** — Pending renewal successfully deleted **401** — Authentication failed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **403** — Authorization failed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **404** — No pending renewal to delete Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **422** — Cannot delete (renewal already completed) Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` # Get CSR status (https://developer.godaddy.com/en/docs/references/rest/ans/get-agent-csr-status-by-agent-id) --- title: Get CSR status description: Retrieves the current status of a Certificate Signing Request (CSR). full: true --- Full description > Retrieves the current status of a Certificate Signing Request (CSR). This endpoint allows clients to check if a CSR has been signed, is still pending, or has been rejected. The failureReason field provides additional context when a CSR is rejected. ## GET /v1/agents/{agentId}/csrs/{csrId}/status Get CSR status Retrieves the current status of a Certificate Signing Request (CSR). This endpoint allows clients to check if a CSR has been signed, is still pending, or has been rejected. The failureReason field provides additional context when a CSR is rejected. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `agentId` | string | yes | Unique identifier of the agent (UUID format) | | `csrId` | string | yes | Unique identifier of the CSR | ### Responses **200** — CSR status retrieved successfully Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/CsrStatusResponse` **401** — Authentication failed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **403** — Authorization failed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **404** — CSR not found or does not belong to this agent Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **422** — Invalid request parameters (semantic validation failure) Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` # Retrieve ANS agent events (https://developer.godaddy.com/en/docs/references/rest/ans/get-agent-events) --- title: Retrieve ANS agent events description: 'Returns a paginated, strictly ordered list of ANS events.' full: true --- Full description Returns a paginated, strictly ordered list of ANS events. When providerId is omitted, the API returns events for all providers; when providerId is provided, only events associated with that provider are returned. Pagination is driven by an opaque cursor token returned in each response. ## GET /v1/agents/events Retrieve ANS agent events Returns a paginated, strictly ordered list of ANS events. When providerId is omitted, the API returns events for all providers; when providerId is provided, only events associated with that provider are returned. Pagination is driven by an opaque cursor token returned in each response. ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `providerId` | string | no | Optional provider identifier. If omitted, global mode is used and the API returns events for all providers from the primary global stream. When provided, results are filtered to only events associated with that provider. | | `lastLogId` | string | no | Optional log id for the last viewed event from a previous request. If not provided, the API returns the first page of results from the start of the event stream. Events are only stored for 30 days. | | `limit` | integer | no | Number of events to return (1-200, default 100) | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | string | no | Unique identifier for request tracking between services (UUID V1 as Base58) | ### Responses **200** — Successful operation Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/EventPageResponse` **400** — Malformed request syntax (invalid JSON, encoding issues) Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **401** — Authentication failed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **403** — Authorization failed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **422** — Invalid request parameters (invalid cursor, out-of-range limit, invalid providerId) Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **429** — Too many requests - throttled Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` # Retrieve agent identity certificates (https://developer.godaddy.com/en/docs/references/rest/ans/get-agent-identity-certificate-by-agent-id) --- title: Retrieve agent identity certificates description: Retrieves all identity certificates for the specified agent full: true --- ## GET /v1/agents/{agentId}/certificates/identity Retrieve agent identity certificates Retrieves all identity certificates for the specified agent ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `agentId` | string | yes | Unique identifier of the agent (UUID format) | ### Responses **200** — Identity certificate(s) retrieved successfully Content-Type: `application/json` Schema: - array - items: **401** — Authentication failed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **403** — Authorization failed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **404** — Agent or certificate not found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` # Retrieve agent server certificates (https://developer.godaddy.com/en/docs/references/rest/ans/get-agent-server-certificate-by-agent-id) --- title: Retrieve agent server certificates description: Retrieves all TLS server certificates for the specified agent full: true --- ## GET /v1/agents/{agentId}/certificates/server Retrieve agent server certificates Retrieves all TLS server certificates for the specified agent ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `agentId` | string | yes | Unique identifier of the agent (UUID format) | ### Responses **200** — Server certificate(s) retrieved successfully Content-Type: `application/json` Schema: - array - items: **401** — Authentication failed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **403** — Authorization failed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **404** — Agent or certificate not found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` # Retrieve agent details (https://developer.godaddy.com/en/docs/references/rest/ans/get-agent) --- title: Retrieve agent details description: Retrieves detailed information about a registered agent full: true --- ## GET /v1/agents/{agentId} Retrieve agent details Retrieves detailed information about a registered agent ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `agentId` | string | yes | Unique identifier of the agent | ### Responses **200** — Agent details retrieved successfully Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/AgentDetails` **401** — Authentication failed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **403** — Authorization failed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **404** — Agent not found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` # Retrieve agent details (https://developer.godaddy.com/en/docs/references/rest/ans/get-registered-agent) --- title: Retrieve agent details description: Returns a single registered agent with trust explainability details. full: true --- Full description Returns a single registered agent with trust explainability details. Search-only ranking scores are not included. ## GET /v1/ans/registered-agents/{agentId} Retrieve agent details Returns a single registered agent with trust explainability details. Search-only ranking scores are not included. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `agentId` | string | yes | Unique agent identifier. | ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `profile` | string | no | Scoring profile name (default: `default`). | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | string | no | Optional request identifier propagated across services. | ### Responses **200** — Successful agent detail retrieval Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/AnsRegisteredAgent` **400** — Malformed request syntax or invalid encoding Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/ErrorResponse` **401** — Authentication info not sent or is invalid Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/ErrorResponse` **403** — Authenticated user is not allowed access Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/ErrorResponse` **404** — Resource not found Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/ErrorResponse` **422** — Request validation failed Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/ErrorResponse` **429** — Too many requests - rate limit exceeded Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/ErrorResponse` **500** — Internal server error Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/ErrorResponse` **502** — Bad gateway or failed dependency Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/ErrorResponse` **503** — Service is temporarily unavailable Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/ErrorResponse` **504** — Gateway or dependency timeout Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/ErrorResponse` # Retrieve pending renewal status (https://developer.godaddy.com/en/docs/references/rest/ans/get-server-certificate-renewal-status) --- title: Retrieve pending renewal status description: >- Returns current server certificate renewal status for the agent, if one exists. full: true --- Full description Returns current server certificate renewal status for the agent, if one exists. Use to check ACME verification progress, poll for certificate issuance, retrieve challenges if the POST response was lost, or get the TLSA record after completion. ## GET /v1/agents/{agentId}/certificates/server/renewal Retrieve pending renewal status Returns current server certificate renewal status for the agent, if one exists. Use to check ACME verification progress, poll for certificate issuance, retrieve challenges if the POST response was lost, or get the TLSA record after completion. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `agentId` | string | yes | Unique identifier of the agent (UUID format) | ### Responses **200** — Renewal found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/RenewalStatus` **401** — Authentication failed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **403** — Authorization failed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **404** — No renewal exists for this agent (never submitted, or previously cancelled/deleted) Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` # List registered agents (https://developer.godaddy.com/en/docs/references/rest/ans/list-registered-agents) --- title: List registered agents description: Lists registered agents using query parameters. full: true --- Full description Lists registered agents using query parameters. Returns a ranked collection; follow pagination links\[].href for subsequent pages. ## GET /v1/ans/registered-agents List registered agents Lists registered agents using query parameters. Returns a ranked collection; follow pagination links[].href for subsequent pages. ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `profile` | string | no | Scoring profile name (default: `default`). | | `query` | string | no | Optional search query string. If omitted and no filters are provided, the API returns all agents except `REVOKED` by default. When `statuses` is explicitly provided, the API uses only the provided status values. Max length is 256 characters by default. When `keywordExtraction=true`, max length is 4096 characters. | | `keywordExtraction` | boolean | no | When true, extracts keywords from the query text before searching. Increases max query length from 256 to 4096 characters. Requires `query` to be non-empty. | | `keywordAlgorithm` | string | no | Keyword extraction algorithm to use when `keywordExtraction=true`. | | `pageSize` | integer | no | Number of results per page (1-100). | | `pageToken` | string | no | Opaque token from a previous response `links[].href` relation (`rel=next` or `rel=prev`). | | `pageTokenDirection` | string | no | Optional token direction when `pageToken` is set. Only valid when `pageToken` is provided. Requests that send `pageTokenDirection` without `pageToken` return `422 INVALID_REQUEST`. | | `totalRequired` | boolean | no | When true, include `totalItems` and `totalPages` in the response envelope. | | `providerIds` | array | no | Filter by provider IDs. | | `statuses` | array | no | Filter by lifecycle statuses. When omitted, default behavior excludes `REVOKED`. | | `agentDomains` | array | no | Agent host domain-family filters. Each value matches apex plus subdomains. | | `protocols` | array | no | Filter by endpoint protocols. | | `transports` | array | no | Filter by endpoint transports. | | `tags` | array | no | Filter by endpoint function tags (`endpoints.functions.tags`). | | `capabilities` | array | no | Filter by function names (`endpoints.functions.name`). | | `scoring.pillarWeights.identity` | integer | no | Identity pillar weight override. | | `scoring.pillarWeights.integrity` | integer | no | Integrity pillar weight override. | | `scoring.thresholds.identity` | integer | no | Identity pillar threshold filter. | | `scoring.thresholds.integrity` | integer | no | Integrity pillar threshold filter. | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | string | no | Optional request identifier propagated across services. | ### Responses **200** — Successful response containing a paged list of registered agents Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/AnsRegisteredAgentsList` **400** — Malformed request syntax or invalid encoding Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/ErrorResponse` **401** — Authentication info not sent or is invalid Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/ErrorResponse` **403** — Authenticated user is not allowed access Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/ErrorResponse` **422** — Request validation failed Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/ErrorResponse` **429** — Too many requests - rate limit exceeded Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/ErrorResponse` **500** — Internal server error Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/ErrorResponse` **502** — Bad gateway or failed dependency Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/ErrorResponse` **503** — Service is temporarily unavailable Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/ErrorResponse` **504** — Gateway or dependency timeout Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/ErrorResponse` # Register a new agent with the ANS (https://developer.godaddy.com/en/docs/references/rest/ans/register-agent) --- title: Register a new agent with the ANS description: Registers a new agent with the Agent Name Service. full: true --- Full description Registers a new agent with the Agent Name Service. Supports GoDaddy domains (synchronous, CSR-based), external domains (async ACME), and bring-your-own-certificate (BYOC, server certificates only). Returns 202 with registration status and any validation requirements. ## POST /v1/agents/register Register a new agent with the ANS Registers a new agent with the Agent Name Service. Supports GoDaddy domains (synchronous, CSR-based), external domains (async ACME), and bring-your-own-certificate (BYOC, server certificates only). Returns 202 with registration status and any validation requirements. ### Request body (required) Agent registration request Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/AgentRegistrationRequest` ### Responses **202** — Registration accepted, validation required (external domains) Content-Type: `application/json` ```json { "agentId": "550e8400-e29b-41d4-a716-446655440000", "ansName": "ans://v1.0.0.external-domain.com", "challenge": { "dnsRecord": { "name": "_acme-challenge.external-domain.com", "type": "TXT", "value": "xyz123abc456" }, "keyAuthorization": "xyz123abc456.thumbprint", "token": "xyz123abc456", "type": "DNS_01" }, "expiresAt": "2025-11-13 16:30:00+00:00", "links": [ { "href": "https://api.godaddy.com/v1/agents/550e8400-e29b-41d4-a716-446655440000/challenge", "rel": "challenge" } ], "nextSteps": [ { "action": "CONFIGURE_DNS", "description": "Configure DNS TXT record for ACME validation", "endpoint": "https://api.godaddy.com/v1/agents/550e8400-e29b-41d4-a716-446655440000/verify-acme" } ], "status": "PENDING_VALIDATION" } ``` Schema: - schema reference: `#/components/schemas/RegistrationPending` **401** — Authentication failed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **403** — Authorization failed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **409** — Agent ID or ANSName already exists Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **422** — Invalid registration request Content-Type: `application/json` ```json { "code": "VALIDATION_ERROR", "details": { "field": "agentDisplayName", "reason": "Field is required but was not provided" }, "message": "Invalid registration request: agentDisplayName is required", "status": "ERROR" } ``` Schema: - schema reference: `#/components/schemas/ErrorResponse` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` # Resolve an ANSName to an endpoint (https://developer.godaddy.com/en/docs/references/rest/ans/resolve-ans-name) --- title: Resolve an ANSName to an endpoint description: Resolves an ANSName to an actionable endpoint reference. full: true --- Full description \| Resolves an ANSName to an actionable endpoint reference. The query includes the ANSName of the target agent and can optionally incorporate capability filters to refine the search. The ANS service queries the Agent Registry, which returns a digitally signed endpoint record if found. ## POST /v1/agents/resolution Resolve an ANSName to an endpoint Resolves an ANSName to an actionable endpoint reference. The query includes the ANSName of the target agent and can optionally incorporate capability filters to refine the search. The ANS service queries the Agent Registry, which returns a digitally signed endpoint record if found. ### Request body (required) Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/AgentCapabilityRequest` ### Responses **200** — Agent endpoint found Content-Type: `application/json` ```json { "ansName": "ans://v1.0.0.myagent.example.com", "links": [ { "href": "https://api.godaddy.com/v1/agents/550e8400-e29b-41d4-a716-446655440000", "rel": "agent-details" }, { "href": "https://myagent.example.com/api/v1", "rel": "agent-endpoint" } ] } ``` Schema: - schema reference: `#/components/schemas/AgentCapabilityResponse` **401** — Authentication failed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **403** — Authorization failed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **404** — Agent not found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **422** — Invalid resolution request Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` # Revoke an active agent or cancel a pending registration (https://developer.godaddy.com/en/docs/references/rest/ans/revoke-agent) --- title: Revoke an active agent or cancel a pending registration description: Revokes an active agent or cancels a pending registration. full: true --- Full description Revokes an active agent or cancels a pending registration. Active agents are added to the Certificate Revocation List. Registrations in PENDING\_VALIDATION status cannot be cancelled through this endpoint and expire automatically. ## POST /v1/agents/{agentId}/revoke Revoke an active agent or cancel a pending registration Revokes an active agent or cancels a pending registration. Active agents are added to the Certificate Revocation List. Registrations in PENDING_VALIDATION status cannot be cancelled through this endpoint and expire automatically. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `agentId` | string | yes | Unique identifier of the agent | ### Request body (required) Agent revocation request Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/AgentRevocationRequest` ### Responses **200** — Agent certificate revoked successfully Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/AgentRevocationResponse` **401** — Authentication failed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **403** — Authorization failed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **404** — Agent not found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **422** — Invalid revocation request (semantic validation failure). Common scenarios: Agent is in DEPRECATED, REVOKED, or EXPIRED state (only ACTIVE or PENDING can be revoked); Attempting to use SUPERSEDED reason (reserved for internal deprecation flow); Agent is in PENDING_VALIDATION state (will automatically expire if verification not completed) Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` # Search the ANSName Registry with flexible criteria (https://developer.godaddy.com/en/docs/references/rest/ans/search-ans-name) --- title: Search the ANSName Registry with flexible criteria description: >- Searches the Agent Name Service registry using flexible criteria such as partial agent names, agent host domains, and version ranges. full: true --- Full description \| Searches the Agent Name Service registry using flexible criteria such as partial agent names, agent host domains, and version ranges. The search can return multiple matching agents along with their metadata and endpoints. Results are paginated to handle large datasets efficiently. ## GET /v1/agents Search the ANSName Registry with flexible criteria Searches the Agent Name Service registry using flexible criteria such as partial agent names, agent host domains, and version ranges. The search can return multiple matching agents along with their metadata and endpoints. Results are paginated to handle large datasets efficiently. ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `agentDisplayName` | string | no | Agent display name (partial matching supported) | | `version` | string | no | Target version (flexible matching supported) | | `agentHost` | string | no | Target agent host domain | | `protocol` | string | no | Target protocol (optional filter) - valid values are 'A2A', 'MCP', 'HTTP-API' | | `limit` | integer | no | Maximum number of results to return (default 20, max 100) | | `offset` | integer | no | Number of results to skip for pagination (default 0) | | `status` | array | no | Filter by agent lifecycle status. Can specify multiple values. Defaults to ACTIVE when not provided. Use 'ALL' to return agents of any status. If 'ALL' is included with other status values, only 'ALL' is applied. | ### Responses **200** — Search completed successfully (may return empty results if no agents match criteria) Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/AgentSearchResponse` **401** — Authentication failed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **403** — Authorization failed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **422** — Invalid search parameters (e.g., invalid pagination values) Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` # Search registered agents (https://developer.godaddy.com/en/docs/references/rest/ans/search-registered-agents) --- title: Search registered agents description: >- Searches registered agents using request-body criteria and returns ranked results. full: true --- ## POST /v1/ans/search-registered-agents Search registered agents Searches registered agents using request-body criteria and returns ranked results. ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | string | no | Optional request identifier propagated across services. | ### Request body (required) Search parameters Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/AnsRegisteredAgentsSearchRequest` ### Responses **200** — Successful response containing a paged list of registered agents Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/AnsRegisteredAgentsList` **400** — Malformed request syntax or invalid encoding Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/ErrorResponse` **401** — Authentication info not sent or is invalid Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/ErrorResponse` **403** — Authenticated user is not allowed access Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/ErrorResponse` **415** — Unsupported or missing media type Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/ErrorResponse` **422** — Request validation failed Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/ErrorResponse` **429** — Too many requests - rate limit exceeded Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/ErrorResponse` **500** — Internal server error Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/ErrorResponse` **502** — Bad gateway or failed dependency Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/ErrorResponse` **503** — Service is temporarily unavailable Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/ErrorResponse` **504** — Gateway or dependency timeout Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/ErrorResponse` # Submit identity certificate CSR (https://developer.godaddy.com/en/docs/references/rest/ans/submit-agent-identity-csr-by-agent-id) --- title: Submit identity certificate CSR description: >- Submits a Certificate Signing Request (CSR) for the agent's identity certificate. full: true --- Full description > Submits a Certificate Signing Request (CSR) for the agent's identity certificate. The response contains a "csrId", that is going to match the same field from CertificateResponse. ## POST /v1/agents/{agentId}/certificates/identity Submit identity certificate CSR Submits a Certificate Signing Request (CSR) for the agent's identity certificate. The response contains a "csrId", that is going to match the same field from CertificateResponse. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `agentId` | string | yes | Unique identifier of the agent (UUID format) | ### Request body (required) CSR submission request Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/CsrSubmissionRequest` ### Responses **202** — CSR accepted for processing Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/CsrSubmissionResponse` **401** — Authentication failed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **403** — Authorization failed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **404** — Agent not found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **422** — Invalid CSR request (semantic validation failure) Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` # Submit server certificate renewal request (https://developer.godaddy.com/en/docs/references/rest/ans/submit-server-certificate-renewal) --- title: Submit server certificate renewal request description: Initiates server certificate renewal. full: true --- Full description Initiates server certificate renewal. Returns ACME challenges that the caller must verify using POST verify-acme. Supports a CSR path (RA issues the certificate) and a BYOC path (caller provides the certificate). Only one pending renewal is allowed per agent; 409 if one already exists. ## POST /v1/agents/{agentId}/certificates/server/renewal Submit server certificate renewal request Initiates server certificate renewal. Returns ACME challenges that the caller must verify using POST verify-acme. Supports a CSR path (RA issues the certificate) and a BYOC path (caller provides the certificate). Only one pending renewal is allowed per agent; 409 if one already exists. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `agentId` | string | yes | Unique identifier of the agent (UUID format) | ### Request body (required) Renewal request (CSR or BYOC) Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ServerCertificateRenewal` ### Responses **202** — Renewal request accepted. Returns ACME challenges for domain validation; the caller must complete verification using POST verify-acme. For the CSR path, the response also includes a csrId for tracking. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/RenewalSubmission` **401** — Authentication failed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **403** — Authorization failed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **404** — Agent not found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **409** — Pending renewal already exists for this agent Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **422** — Validation failed: - Agent not ACTIVE - Neither serverCsrPEM nor serverCertificatePEM provided - Both serverCsrPEM and serverCertificatePEM provided - CSR validation failed (SAN/CN mismatch) - BYOC cert validation failed (expired, SAN/CN mismatch) - serverCertificateChainPEM provided without serverCertificatePEM Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` # Trigger ACME validation (https://developer.godaddy.com/en/docs/references/rest/ans/validate-registration) --- title: Trigger ACME validation description: >- Initiates domain control validation after the ACME challenge token has been placed at the specified location. full: true --- Full description Initiates domain control validation after the ACME challenge token has been placed at the specified location. The RA determines the validation method automatically based on the registration configuration. ## POST /v1/agents/{agentId}/verify-acme Trigger ACME validation Initiates domain control validation after the ACME challenge token has been placed at the specified location. The RA determines the validation method automatically based on the registration configuration. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `agentId` | string | yes | Unique identifier of the agent | ### Responses **202** — Validation successful, certificates pending Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/AgentStatus` **401** — Authentication failed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **403** — Authorization failed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **404** — Agent not found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **422** — Validation failed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` # Verify ACME challenges for pending server cert renewal (https://developer.godaddy.com/en/docs/references/rest/ans/verify-acme-challenges) --- title: Verify ACME challenges for pending server cert renewal description: Triggers ACME validation for a pending server certificate renewal. full: true --- Full description Triggers ACME validation for a pending server certificate renewal. Verifies the DNS-01 (TXT record) and HTTP-01 (file at /.well-known/acme-challenge) challenges. Returns 202 for CSR renewals (async issuance) or 200 for BYOC renewals (certificate stored). ## POST /v1/agents/{agentId}/certificates/server/renewal/verify-acme Verify ACME challenges for pending server cert renewal Triggers ACME validation for a pending server certificate renewal. Verifies the DNS-01 (TXT record) and HTTP-01 (file at /.well-known/acme-challenge) challenges. Returns 202 for CSR renewals (async issuance) or 200 for BYOC renewals (certificate stored). ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `agentId` | string | yes | Unique identifier of the agent (UUID format) | ### Responses **200** — BYOC renewal completed synchronously. TLSA record returned for DNS update. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/RenewalVerification` **202** — CSR renewal validation succeeded. Certificate issuance in progress (poll GET /certificates/server). Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/RenewalVerification` **401** — Authentication failed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **403** — Authorization failed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **404** — No pending renewal found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **422** — Validation failed: - No pending renewal found - Renewal expired (>7 days old) - ACME challenges not found in DNS/HTTP - Agent not ACTIVE Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` # Verify DNS record configuration (https://developer.godaddy.com/en/docs/references/rest/ans/verify-dns-records) --- title: Verify DNS record configuration description: Verifies that all required DNS records have been configured correctly. full: true --- Full description \| Verifies that all required DNS records have been configured correctly. The RA knows which records are required based on the registration and will check for all four required records (HTTPS, TLSA, \_ans, \_ra-badge). This is the final step for external domain registration. ## POST /v1/agents/{agentId}/verify-dns Verify DNS record configuration Verifies that all required DNS records have been configured correctly. The RA knows which records are required based on the registration and will check for all four required records (HTTPS, TLSA, _ans, _ra-badge). This is the final step for external domain registration. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `agentId` | string | yes | Unique identifier of the agent | ### Responses **202** — DNS verified, registration active Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/AgentStatus` **401** — Authentication failed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **403** — Authorization failed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **404** — Agent not found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` **422** — DNS records not found or incorrect Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/DnsVerificationError` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorResponse` # Check aftermarket listing availability (https://developer.godaddy.com/en/docs/references/rest/auctions/check-listing-availability) --- title: Check aftermarket listing availability description: >- Accepts a domains array of 1-50 FQDNs and returns one result per input domain in order, with AVAILABLE or UNAVAILABLE status. full: true --- Full description Accepts a domains array of 1-50 FQDNs and returns one result per input domain in order, with AVAILABLE or UNAVAILABLE status. Optionally include listing details or domain enrichment signals using the includes query parameter. ## POST /v1/customers/{customerId}/aftermarket/listings/available Check aftermarket listing availability Accepts a domains array of 1-50 FQDNs and returns one result per input domain in order, with AVAILABLE or UNAVAILABLE status. Optionally include listing details or domain enrichment signals using the includes query parameter. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `customerId` | string | yes | Customer identifier (UUID). Use `MY` for the authenticated customer's own data, or supply the UUID returned by `GET /v1/shoppers/{shopperId}?includes=customerId`. | ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `currencyId` | string | no | ISO-4217 currency code for all monetary fields (e.g. `USD`, `EUR`). Defaults to `USD`. | | `includes` | string | no | Comma-separated field groups to include on each AVAILABLE result. Allowed tokens: `listingMin`, `listing`, `enrichment`. `listing` and `listingMin` are mutually exclusive. | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | string | no | Optional client-supplied request correlation ID. Echoed in the response `X-Request-Id` header. | ### Request body (required) Request body containing the domains to check. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/AvailabilityCheckRequest` ### Responses **200** — Returned for every valid request. Inspect `availabilities[i].status` per domain — UNAVAILABLE domains are still a 200. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/AvailabilityResponse` **400** — Request was malformed — missing or empty `domains` array, more than 50 domains, or unknown `includes` token. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or invalid. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access (e.g. `{customerId}` does not match JWT `customer` claim). Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **422** — Mutually-exclusive `includes` tokens supplied (`listing` and `listingMin` together). Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error — upstream dependency (database or FIND) is unreachable or an unexpected error occurred. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` # Purchase closeout auction domains (https://developer.godaddy.com/en/docs/references/rest/auctions/create-purchase) --- title: Purchase closeout auction domains full: true --- ## POST /v1/customers/{customerId}/auctions/purchases Purchase closeout auction domains ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `customerId` | string | yes | Customer identifier (UUID). Use `MY` for the authenticated customer's own data, or supply the UUID returned by `GET /v1/shoppers/{shopperId}?includes=customerId`. | ### Request body (required) The payment profile and list of domains to purchase Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/PurchaseCreate` ### Responses **200** — All domains purchased successfully Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Purchase` **207** — Some domains purchased successfully; others failed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Purchase` **400** — Request was malformed. Also returned for NO_ELIGIBLE_PAYMENT_PROFILE and UNSUPPORTED_CURRENCY. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **422** — Required parameters must be specified in correct format. Also returned for PAYMENT_FAILED. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` # Get eligible payment profiles for instant purchase (https://developer.godaddy.com/en/docs/references/rest/auctions/get-payment-profiles) --- title: Get eligible payment profiles for instant purchase full: true --- ## GET /v1/customers/{customerId}/paymentProfiles Get eligible payment profiles for instant purchase ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `customerId` | string | yes | Customer identifier (UUID). Use `MY` for the authenticated customer's own data, or supply the UUID returned by `GET /v1/shoppers/{shopperId}?includes=customerId`. | ### Responses **200** — Request was successful Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/PaymentProfiles` **400** — Request was malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` # Place multiple bids (https://developer.godaddy.com/en/docs/references/rest/auctions/place-bids) --- title: Place multiple bids full: true --- ## POST /v1/customers/{customerId}/aftermarket/listings/bids Place multiple bids ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `customerId` | string | yes | Customer identifier (UUID). Use `MY` for the authenticated customer's own data, or supply the UUID returned by `GET /v1/shoppers/{shopperId}?includes=customerId`. | ### Request body (required) An array of bids to be placed. Content-Type: `application/json` Schema: - array - items: ### Responses **200** — All bids placed successfully. Content-Type: `application/json` ```json [ { "listingId": 200000, "isHighestBidder": "true", "bidId": "e8f0a45d-53c6-49e5-a1f2-08b993960e1b", "bidAmountUsd": 100000000, "status": "SUCCESS" } ] ``` Schema: - array - items: **207** — Partial success. Content-Type: `application/json` ```json [ { "listingId": 200000, "isHighestBidder": "true", "bidId": "e8f0a45d-53c6-49e5-a1f2-08b993960e1b", "bidAmountUsd": 100000000, "status": "SUCCESS" }, { "listingId": 300000, "bidAmountUsd": 100000000, "bidFailureReason": "BID_MIN_NOT_MET", "status": "FAILED" } ] ``` Schema: - array - items: **400** — Query string and/or request body are malformed Content-Type: `application/json` ```json { "code": "MALFORMED_INPUT", "message": "The request was malformed" } ``` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or is invalid Content-Type: `application/json` ```json { "code": "UNABLE_TO_AUTHENTICATE", "message": "Unauthorized : Could not authenticate API key/secret" } ``` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` ```json { "code": "MISSING_CREDENTIALS", "message": "Unauthorized : Credentials must be specified" } ``` Schema: - schema reference: `#/components/schemas/Error` **422** — Application-specific request error Content-Type: `application/json` ```json { "code": "DUPLICATE_BIDS", "message": "Bidding request contains multiple bids for listingID 200000" } ``` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` ```json { "code": "TOO_MANY_REQUESTS", "message": "Too many requests received within interval" } ``` Schema: - schema reference: `#/components/schemas/Error` **500** — Internal server error Content-Type: `application/json` ```json { "code": "SERVER_ERROR", "message": "Internal server error" } ``` Schema: - schema reference: `#/components/schemas/Error` # Preview pricing for closeout auction domains (https://developer.godaddy.com/en/docs/references/rest/auctions/preview-purchase) --- title: Preview pricing for closeout auction domains full: true --- ## POST /v1/customers/{customerId}/auctions/purchases/preview Preview pricing for closeout auction domains ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `customerId` | string | yes | Customer identifier (UUID). Use `MY` for the authenticated customer's own data, or supply the UUID returned by `GET /v1/shoppers/{shopperId}?includes=customerId`. | ### Request body (required) An object containing the list of domain names to preview pricing for Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/PurchasePreviewCreate` ### Responses **200** — Pricing retrieved for all domains Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/PurchasePreview` **207** — Pricing retrieved for some domains; others failed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/PurchasePreview` **400** — Request was malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **422** — Required parameters must be specified in correct format Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` # Catalog GraphQL (https://developer.godaddy.com/en/docs/references/rest/catalog) --- title: Catalog GraphQL description: Query and mutate the commerce catalog subgraph for a store. full: true --- Store-scoped catalog GraphQL over HTTP. Use `commerce.product:read` to query and `commerce.product:write` to mutate. See [Commerce API Scopes](https://developer.godaddy.com/docs/references/rest/commerce-scopes). **Endpoint:** `POST /v2/commerce/stores/{storeId}/catalog-subgraph` Send the same store ID in the `{storeId}` path and the `x-store-id` header. The header is required. If they differ, the subgraph uses the header. **Rate limit:** Read `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` on every response. On HTTP `429`, wait for `RateLimit-Reset` or `Retry-After`. See [Handle rate limits](https://developer.godaddy.com/docs/api-users/rate-limits). ## Resource IDs Examples use placeholders such as `ID_VALUE`, `SKU_ID`, and `LOCATION_ID`. Replace them with ids from your store before calling live APIs. 1. **List** — run the matching query with `first` (for example [`locations`](https://developer.godaddy.com/docs/references/rest/catalog/inventory/queries/locations), [`skus`](https://developer.godaddy.com/docs/references/rest/catalog/sku/queries/skus), [`skuGroups`](https://developer.godaddy.com/docs/references/rest/catalog/sku-group/queries/skuGroups)). 2. **Create** — call a create mutation and read `id` from the response (for example [`createSkuGroup`](https://developer.godaddy.com/docs/references/rest/catalog/sku-group/mutations/createSkuGroup)). 3. **Reuse** — pass that id in the next call's `id` argument or input field (`skuId`, `locationId`, `skuGroupIds`, and so on). Nested response fields (`prices`, `values`, `references`) also expose `id` when you need a child resource. For `SimpleMoneyInput.value`, send `1999` for $19.99 USD, not `19.99`. Copy the sample variables as-is (`1000`) or convert dollars to cents before calling. The GraphQL domain model uses **SKU** / **SKU group** (not a `Product` type). PAT scopes stay `commerce.product:*` for historical naming. Sidebar is grouped by **action/resource**. Expand a resource, then **Query** (`commerce.product:read`, 27 fields) or **Mutation** (`commerce.product:write`, 108 fields). ## Example query query Requires `commerce.product:read`. See [`sku`](https://developer.godaddy.com/docs/references/rest/catalog/sku/queries/sku) for the full schema. ```graphql query GetSku($id: String!) { sku(id: $id) { id name status } } ``` ```bash curl -X POST "https://api.godaddy.com/v2/commerce/stores/{storeId}/catalog-subgraph" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "Content-Type: application/json" \ -H "x-store-id: {storeId}" \ -d '{ "query": "query GetSku($id: String!) { sku(id: $id) { id name status } }", "variables": { "id": "SKU_ID" } }' ``` ## Example mutation mutation Requires `commerce.product:write`. See [`createSku`](https://developer.godaddy.com/docs/references/rest/catalog/sku/mutations/createSku) for the full schema. ```graphql mutation CreateSku($input: CreateSKUInput!) { createSku(input: $input) { id name status } } ``` *** ## HTTP reference OpenAPI contract for the subgraph POST (headers, auth, response envelope): ## POST /stores/{storeId}/catalog-subgraph Catalog GraphQL endpoint Proxies GraphQL to the catalog subgraph. Use the `query` field for the GraphQL document and optional `variables` / `operationName`. Send the same store ID in the `{storeId}` path and the `x-store-id` header. The header is required. If they differ, the subgraph uses the header. This endpoint is rate-limited per credential per window. Read the RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset response headers; do not assume 60 requests per minute. Exceeding the live limit returns HTTP 429; honor RateLimit-Reset or Retry-After before retrying. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `storeId` | unknown | yes | | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `x-store-id` | unknown | yes | Required store ID. Send the same value as `{storeId}` in the path. If they differ, the subgraph uses this header. | ### Request body (required) Content-Type: `application/json` ```json { "query": "query GetSku($id: String!) { sku(id: $id) { id name status } }", "variables": { "id": "SKU_ID" } } ``` Schema: - object - `query` (required): string - `variables`: object - `operationName`: string ### Responses **200** — GraphQL response. RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset are present on every response (including 200). Content-Type: `application/json` Schema: - object - `data`: object - `errors`: array - items: **400** — Invalid request Content-Type: `application/json` Schema: - schema reference: `#/x-ext/f5fae09` **401** — Unauthorized Content-Type: `application/json` Schema: - schema reference: `#/x-ext/f5fae09` **403** — Forbidden Content-Type: `application/json` Schema: - schema reference: `#/x-ext/f5fae09` **404** — Store not found Content-Type: `application/json` Schema: - schema reference: `#/x-ext/f5fae09` **429** — Rate limit exceeded (RateLimit-Remaining is 0). Wait RateLimit-Reset seconds. Honor Retry-After when the gateway sends it. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/f5fae09` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/x-ext/f5fae09` **Security:** requires `PAT`; scopes `commerce.product:read`, `commerce.product:write`. # v1 (https://developer.godaddy.com/en/docs/references/rest/certificates/v1) --- title: v1 description: '' full: true --- ## POST /v1/certificates Create a pending order for certificate

Creating a certificate order can be a long running asynchronous operation in the PKI workflow. The PKI API supports 2 options for getting the completion stateful actions for this asynchronous operations: 1) by polling operations -- see /v1/certificates/{certificateId}/actions 2) via WebHook style callback -- see '/v1/certificates/{certificateId}/callback'.

### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Market-Id` | string | no | Setting locale for communications such as emails and error messages | ### Request body (required) The certificate order information Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/CertificateCreate` ### Responses **202** — Request was successful Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/CertificateIdentifier` **400** — Request was malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **409** — Certificate state does not allow renew Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **422** — `email` is not empty
`csr` is invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` ## POST /v1/certificates/validate Validate a pending order for certificate ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Market-Id` | string | no | Setting locale for communications such as emails and error messages | ### Request body (required) The certificate order info Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/CertificateCreate` ### Responses **204** — Request validated successfully **400** — Request was malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **409** — Certificate state does not allow renew Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **422** — `email` is not empty
`csr` is invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` ## GET /v1/certificates/{certificateId} Retrieve certificate details Once the certificate order has been created, this method can be used to check the status of the certificate. This method can also be used to retrieve details of the certificate. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `certificateId` | string | yes | Certificate id to lookup | ### Responses **200** — Certificate details retrieved Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Certificate` **400** — Request was malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — Certificate id not found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` ## GET /v1/certificates/{certificateId}/actions Retrieve all certificate actions This method is used to retrieve all stateful actions relating to a certificate lifecycle. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `certificateId` | string | yes | Certificate id to register for callback | ### Responses **200** — Action retrieval successful Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ArrayOfCertificateAction` **400** — Request was malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — Certificate not found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` ## POST /v1/certificates/{certificateId}/email/{emailId}/resend Resend an email This method can be used to resend emails by providing the certificate id and the email id ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `certificateId` | string | yes | Certificate id to resend email | | `emailId` | string | yes | Email id for email to resend | ### Responses **204** — Email sent successfully **404** — Certificate not found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **409** — Email Id not found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` ## POST /v1/certificates/{certificateId}/email/resend/{emailAddress} Add alternate email address This method adds an alternate email address to a certificate order and re-sends all existing request emails to that address. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `certificateId` | string | yes | Certificate id to resend emails | | `emailAddress` | string | yes | Specific email address to resend email | ### Responses **200** — Alternate email address added and emails re-sent Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/CertificateEmailHistory` **404** — Certificate not found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **409** — Certificate state does not allow alternate email address Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` ## POST /v1/certificates/{certificateId}/email/{emailId}/resend/{emailAddress} Resend email to email address This method can be used to resend emails by providing the certificate id, the email id, and the recipient email address ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `certificateId` | string | yes | Certificate id to resend emails | | `emailId` | string | yes | Email id for email to resend | | `emailAddress` | string | yes | Specific email address to resend email | ### Responses **204** — Email sent successfully **404** — Certificate not found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **409** — Email Id not found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` ## GET /v1/certificates/{certificateId}/email/history Retrieve email history This method can be used to retrieve all emails sent for a certificate. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `certificateId` | string | yes | Certificate id to retrieve email history | ### Responses **200** — Email history retrieval successful Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/CertificateEmailHistory` **409** — Email history not found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` ## GET /v1/certificates/{certificateId}/callback Retrieve system stateful action callback url This method is used to retrieve the registered callback url for a certificate. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `certificateId` | string | yes | Certificate id to register for stateful action callback | ### Responses **200** — Callback registered Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/CertificateCallback` **400** — Request was malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — Certificate id not found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` ## DELETE /v1/certificates/{certificateId}/callback Unregister system callback Unregister the callback for a particular certificate. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `certificateId` | string | yes | Certificate id to unregister callback | ### Responses **204** — Callback removed **400** — Request was malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — Certificate id not found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` ## PUT /v1/certificates/{certificateId}/callback Register of certificate action callback This method is used to register/replace url for callbacks for stateful actions relating to a certificate lifecycle. The callback url is a Webhook style pattern and will receive POST http requests with json body defined in the CertificateAction model definition for each certificate action. Only one callback URL is allowed to be registered for each certificateId, so it will replace a previous registration. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `certificateId` | string | yes | Certificate id to register/replace for callback | ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `callbackUrl` | string | yes | Callback url registered/replaced to receive stateful actions | ### Responses **204** — Callback replaced/registered **400** — Request was malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — Certificate id not found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **422** — Callback url is missing
Callback url is malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` ## POST /v1/certificates/{certificateId}/cancel Cancel a pending certificate Use the cancel call to cancel a pending certificate order. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `certificateId` | string | yes | Certificate id to cancel | ### Responses **204** — Certificate order has been canceled **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — Certificate id not found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **409** — Certificate state does not allow cancel Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` ## GET /v1/certificates/{certificateId}/download Download certificate ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `certificateId` | string | yes | Certificate id to download | ### Responses **200** — Certificate retrieved Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/CertificateBundle` **400** — Request was malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — Certificate id not found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **409** — Certificate state does not allow download Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` ## POST /v1/certificates/{certificateId}/reissue Reissue active certificate

Rekeying is the process by which the private and public key is changed for a certificate. It is a simplified reissue,where only the CSR is changed. Reissuing is the process by which domain names are added or removed from a certificate.Once a request is validated and approved, the certificate will be reissued with the new common name and sans specified. Unlimited reissues are available during the lifetime of the certificate.New names added to a certificate that do not share the base domain of the common name may take additional time to validate. If this API call is made before a previous pending reissue has been validated and issued, the previous reissue request is automatically rejected and replaced with the current request.

### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `certificateId` | string | yes | Certificate id to reissue | ### Request body (required) The reissue request info Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/CertificateReissue` ### Responses **202** — Reissue request created **400** — Request was malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — Certificate id not found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **409** — Certificate state does not allow reissue Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **422** — `csr` is invalid
Delay revocation exceeds maximum Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` ## POST /v1/certificates/{certificateId}/renew Renew active certificate Renewal is the process by which the validity of a certificate is extended. Renewal is only available 60 days prior to expiration of the previous certificate and 30 days after the expiration of the previous certificate. The renewal supports modifying a set of the original certificate order information. Once a request is validated and approved, the certificate will be issued with extended validity. Since subject alternative names can be removed during a renewal, we require that you provide the subject alternative names you expect in the renewed certificate. New names added to a certificate that do not share the base domain of the common name may take additional time to validate.

### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `certificateId` | string | yes | Certificate id to renew | ### Request body (required) The renew request info Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/CertificateRenew` ### Responses **202** — Renew request created **400** — Request was malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — Certificate id not found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **409** — Certificate state does not allow renew Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **422** — `csr` is invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` ## POST /v1/certificates/{certificateId}/revoke Revoke active certificate Use revoke call to revoke an active certificate, if the certificate has not been issued a 404 response will be returned. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `certificateId` | string | yes | Certificate id to revoke | ### Request body (required) The certificate revocation request Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/CertificateRevoke` ### Responses **204** — Certificate Revoked **400** — Request was malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — Certificate id not found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **409** — Certificate state does not allow revoke Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` ## GET /v1/certificates/{certificateId}/siteSeal Get Site seal

This method is used to obtain the site seal information for an issued certificate. A site seal is a graphic that the certificate purchaser can embed on their web site to show their visitors information about their SSL certificate. If a web site visitor clicks on the site seal image, a pop-up page is displayed that contains detailed information about the SSL certificate. The site seal token is used to link the site seal graphic image to the appropriate certificate details pop-up page display when a user clicks on the site seal. The site seal images are expected to be static images and hosted on the reseller's website, to minimize delays for customer page load times.

### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `certificateId` | string | yes | Certificate id | ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `theme` | string | no | This value represents the visual theme of the seal. If seal doesn't exist, default values are used if params not present. If seal does exist, default values will not be used to update unless params present. | | `locale` | string | no | Determine locale for text displayed in seal image and verification page. If seal doesn't exist, default values are used if params not present. If seal does exist, default values will not be used to update unless params present. | ### Responses **200** — Site seal retrieved Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/CertificateSiteSeal` **400** — Request was malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — Certificate id not found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **409** — Certificate state does not allow seal Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **422** — 'locale' is invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` ## POST /v1/certificates/{certificateId}/verifyDomainControl Check Domain Control Domain control is a means for verifying the domain included in the certificate order. This resource is useful for resellers that control the domains for their customers, and can expedite the verification process. See https://www.godaddy.com/help/verifying-your-domain-ownership-for-ssl-certificate-requests-html-or-dns-7452 ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `certificateId` | string | yes | Certificate id to lookup | ### Responses **204** — Domain control was successful **400** — Request was malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — Certificate id not found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **409** — Domain control was not successful
Certificate state does not allow domain control Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` # v2 (https://developer.godaddy.com/en/docs/references/rest/certificates/v2) --- title: v2 description: '' full: true --- ## GET /v2/certificates Search for certificate details by entitlement Once the certificate order has been created, this method can be used to check the status of the certificate. This method can also be used to retrieve details of the certificates associated to an entitlement. ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `entitlementId` | string | yes | Entitlement id to lookup | | `latest` | boolean | no | Fetch only the most recent certificate | ### Responses **200** — Certificate details retrieved Content-Type: `application/json` Schema: - array - items: **400** — Request was malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **422** — Entitlement id not provided Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` ## POST /v2/certificates Create a pending order for certificate

Creating a certificate order for a subscription can be a long running asynchronous operation in the PKI workflow. The PKI API supports 2 options for getting the completion stateful actions for this asynchronous operations: 1) by polling operations -- see /v1/certificates/{certificateId}/actions 2) via WebHook style callback -- see '/v1/certificates/{certificateId}/callback'.

### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Market-Id` | string | no | Setting locale for communications such as emails and error messages | ### Request body (required) The certificate order information Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/SubscriptionCertificateCreate` ### Responses **202** — Request was successful Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/SubscriptionCertificateIdentifier` **400** — Request was malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **409** — Certificate state does not allow renew Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **422** — `email` is not empty
`csr` is invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` ## POST /v2/certificates/{certificateId}/reissue Reissue active certificate

Rekeying is the process by which the private and public key is changed for a certificate. It is a simplified reissue,where only the CSR is changed. Reissue extends validity of the existing certificate by requesting a new certificate with all the same values as existing issued certificate. Once a request is validated and approved, the certificate will be reissued with the same common name and sans specified from existing certificate. Unlimited reissues are available during the lifetime of the certificate.If this API call is made before a previous pending reissue has been validated and issued, the previous reissue request is automatically rejected and replaced with the current request.

### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `certificateId` | string | yes | Certificate id to reissue | ### Request body The reissue request info Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/CertificateReissueV2` ### Responses **202** — Reissue request created **400** — Request was malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — Certificate id not found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **409** — Certificate state does not allow reissue Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **422** — `csr` is invalid
Delay revocation exceeds maximum Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` ## GET /v2/certificates/download Download certificate by entitlement ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `entitlementId` | string | yes | Entitlement id to download | ### Responses **200** — Certificate retrieved Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/CertificateBundle` **400** — Request was malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — Entitlement id not found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **409** — Certificate state does not allow download Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **422** — Entitlement id not provided Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` ## GET /v2/customers/{customerId}/certificates Retrieve customer's certificates This method can be used to retrieve a list of certificates for a specified customer.
  • **shopperId** is **not the same** as **customerId**. **shopperId** is a number of max length 10 digits (*ex:* 1234567890) whereas **customerId** is a UUIDv4 (*ex:* 295e3bc3-b3b9-4d95-aae5-ede41a994d13)
### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `customerId` | string | yes | An identifier for a customer | ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `offset` | integer | no | Number of results to skip for pagination | | `limit` | integer | no | Maximum number of items to return | ### Responses **200** — Customer certificate information retrieved. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/CertificateSummariesV2` **401** — Authentication info not sent or is invalid Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` **422** — Application-specific request error Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` ## GET /v2/customers/{customerId}/certificates/{certificateId} Retrieve individual certificate details Once the certificate order has been created, this method can be used to check the status of the certificate. This method can also be used to retrieve details of the certificate.
  • **shopperId** is **not the same** as **customerId**. **shopperId** is a number of max length 10 digits (*ex:* 1234567890) whereas **customerId** is a UUIDv4 (*ex:* 295e3bc3-b3b9-4d95-aae5-ede41a994d13)
### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `customerId` | string | yes | An identifier for a customer | | `certificateId` | string | yes | Certificate id to lookup | ### Responses **200** — Certificate details retrieved Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/CertificateDetailV2` **401** — Authentication info not sent or is invalid Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` **404** — Resource not found Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` **422** — Application-specific request error Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` ## GET /v2/customers/{customerId}/certificates/{certificateId}/domainVerifications Retrieve domain verification status This method can be used to retrieve the domain verification status for a certificate request.
  • **shopperId** is **not the same** as **customerId**. **shopperId** is a number of max length 10 digits (*ex:* 1234567890) whereas **customerId** is a UUIDv4 (*ex:* 295e3bc3-b3b9-4d95-aae5-ede41a994d13)
" ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `customerId` | string | yes | An identifier for a customer | | `certificateId` | string | yes | Certificate id to lookup | ### Responses **200** — Domain verification status list for specified certificateId. Content-Type: `application/json` Schema: - array - items: **401** — Authentication info not sent or is invalid Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` **404** — Resource not found Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` **422** — Application-specific request error Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` ## GET /v2/customers/{customerId}/certificates/{certificateId}/domainVerifications/{domain} Retrieve detailed information for supplied domain Retrieve detailed information for supplied domain, including domain verification details and Certificate Authority Authorization (CAA) verification details.
  • **shopperId** is **not the same** as **customerId**. **shopperId** is a number of max length 10 digits (*ex:* 1234567890) whereas **customerId** is a UUIDv4 (*ex:* 295e3bc3-b3b9-4d95-aae5-ede41a994d13)
### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `customerId` | string | yes | An identifier for a customer | | `certificateId` | string | yes | Certificate id to lookup | | `domain` | string | yes | A valid domain name in the certificate request | ### Responses **200** — Retrieve detailed information for supplied domain, including domain verification details and Certificate Authority Authorization (CAA) verification details. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/DomainVerificationDetail` **401** — Authentication info not sent or is invalid Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` **404** — Resource not found Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` **422** — Application-specific request error Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` ## GET /v2/customers/{customerId}/certificates/acme/externalAccountBinding Retrieves the external account binding for the specified customer Use this endpoint to retrieve a key identifier and Hash-based Message Authentication Code (HMAC) key for Automated Certificate Management Environment (ACME) External Account Binding (EAB). These credentials can be used with an ACME client that supports EAB (ex. CertBot) to automate the issuance request and deployment of DV SSL certificates ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `customerId` | string | yes | An identifier for a customer | ### Responses **200** — Acme key identifier and HMAC key for the external account binding. Directory URI is also provided for making ACME requests. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ExternalAccountBinding` **401** — Authentication info not sent or is invalid Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` **404** — Resource not found Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` **422** — Application-specific request error Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` ## GET /v2/certificates/subscriptions/search Get a page of subscriptions by domain The pagination starts at page 1. Each page contains a page of *subscriptions*, not certificates. This endpoint is meant for paging the subscriptions under the authorized user's account. Each subscription contains a snapshot of certificates contained within the subscription. To fetch further certificates under a subscription, use the /v2/certificates/subscription/{guid} endpoint with the subscription GUID obtained from this call. If any filtering is applied, subscriptions without any certificates will be omitted. ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `pageSize` | integer | no | The number of records to return per query. | | `page` | integer | no | The page number. (First page is one instead of zero.) | | `domain` | string | no | Filter by domain name / common name. This will look for the text inside the content of the domain. This is not a "find domains that start with x" search. | | `status` | string | no | The certificate lifecycle stage.
Active, Expired, and Revoked are all Issued certificates.
Active means the validity period includes today.
Expired means the validity period was prior to today.
Revoked means that the certificate has been revoked.
Pending means that the certificate is still going through the issuance process and has not been signed or issued yet.
Denied means that the certificate went from pending to denied for any valid denial reason. (Customer canceled request, CAA records exist for the domain, fraud, etc...) | | `type` | string | no | The type of certificate in terms of the number of applicable domains. | | `validation` | string | no | The validation type for the certificate. Standard/Basic Validation (DV). Organizational/Deluxe Vetting (OV). Extended/Premium Validation (EV). | ### Responses **200** — OK Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/CertificatesByDomainPage` ## GET /v2/certificates/subscription/{guid} GET a page of certificates for a specific domain product ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `guid` | string | yes | The Subscription GUID containing the certificates being requested. | ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `pageSize` | integer | no | The number of records to return per query. | | `page` | integer | no | The page number. (First page is one instead of zero.) | | `domain` | string | no | Filter by domain name / common name. This will look for the text inside the content of the domain. This is not a "find domains that start with x" search. | | `status` | string | no | The certificate lifecycle stage.
Active, Expired, and Revoked are all Issued certificates.
Active means the validity period includes today.
Expired means the validity period was prior to today.
Revoked means that the certificate has been revoked.
Pending means that the certificate is still going through the issuance process and has not been signed or issued yet.
Denied means that the certificate went from pending to denied for any valid denial reason. (Customer canceled request, CAA records exist for the domain, fraud, etc...) | | `type` | string | no | The type of certificate in terms of the number of applicable domains. | | `validation` | string | no | The validation type for the certificate. Standard/Basic Validation (DV). Organizational/Deluxe Vetting (OV). Extended/Premium Validation (EV). | ### Responses **200** — OK Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/CertificatesByDomainPaged` # Get channel by ID (https://developer.godaddy.com/en/docs/references/rest/channels/get-channel-by-id) --- title: Get channel by ID description: Returns a single channel by ID. full: true --- Full description Returns a single channel by ID. Access requires a service principal in GLOBAL or channel-scoped customer permissions. Authorization is checked before existence; an unknown channelId might return 401 instead of 404. ## GET /channels/{channelId} Get channel by ID Returns a single channel by ID. Access requires a service principal in GLOBAL or channel-scoped customer permissions. Authorization is checked before existence; an unknown channelId might return 401 instead of 404. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `channelId` | unknown | yes | | ### Responses **200** — Channel Found Content-Type: `application/json` Schema: - schema reference: `#/x-ext/df5646b` **401** — Authentication failed or missing. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/e2dac50` **403** — Caller is authenticated but not authorized for this action. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/e2dac50` **404** — The requested resource was not found. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/e2dac50` **500** — Unexpected server error. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/e2dac50` **Security:** requires `PAT`; scopes `commerce.channel:read`. # Get all channels (https://developer.godaddy.com/en/docs/references/rest/channels/get-channels) --- title: Get all channels description: Returns all channels for a provider. full: true --- Full description Returns all channels for a provider. Requires at least one of registeredStores.storeId or externalChannelId; omitting both returns 400. Access requires a service principal with GLOBAL resource group or a customer with COMMERCE\_STORE access. ## GET /channels Get all channels Returns all channels for a provider. Requires at least one of registeredStores.storeId or externalChannelId; omitting both returns 400. Access requires a service principal with GLOBAL resource group or a customer with COMMERCE_STORE access. ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `externalChannelId` | string | no | | | `registeredStores.storeId` | unknown | no | | | `registeredStores.default` | boolean | null | no | | | `pageSize` | integer | no | | | `page` | integer | no | | | `totalRequired` | boolean | no | When `true`, the response includes `totalItems`, `totalPages`, and a `last` HATEOAS link. When `false` (default), those fields and the `last` link are omitted. | ### Responses **200** — Channels Content-Type: `application/json` Schema: - schema reference: `#/x-ext/b8a4d41` **400** — Invalid request (validation error or missing required parameter). Content-Type: `application/json` Schema: - schema reference: `#/x-ext/e2dac50` **401** — Authentication failed or missing. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/e2dac50` **403** — Caller is authenticated but not authorized for this action. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/e2dac50` **500** — Unexpected server error. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/e2dac50` **Security:** requires `PAT`; scopes `commerce.channel:read`. # Retrieve country information (https://developer.godaddy.com/en/docs/references/rest/countries/get-countries) --- title: Retrieve country information description: Authorization is not required full: true --- ## GET /v1/countries Retrieve country information Authorization is not required ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `marketId` | string | yes | MarketId in which the request is being made, and for which responses should be localized | ### Responses **200** — Request was successful Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ArrayOfCountrySummary` **422** — marketId is required Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` # Retrieve country and state information (https://developer.godaddy.com/en/docs/references/rest/countries/get-country) --- title: Retrieve country and state information description: Authorization is not required full: true --- ## GET /v1/countries/{countryKey} Retrieve country and state information Authorization is not required ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `countryKey` | string | yes | The country key | ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `marketId` | string | yes | MarketId in which the request is being made, and for which responses should be localized | ### Responses **200** — Request was successful Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ArrayOfCountry` **404** — Country not found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **422** — marketId is required Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` # Create a new customer (https://developer.godaddy.com/en/docs/references/rest/customers/commerce-customers-create) --- title: Create a new customer description: >- This endpoint can be used to create or de-duplicate - using channel data - and merge into existing customer. full: true --- Full description This endpoint can be used to create or de-duplicate - using channel data - and merge into existing customer. If the provided channels differ from existing customer data, a new customer will be created. This endpoint will not remove any existing data and is additive in cases where merges occur. ## POST /stores/{storeId}/customers Create a new customer This endpoint can be used to create or de-duplicate - using channel data - and merge into existing customer. If the provided channels differ from existing customer data, a new customer will be created. This endpoint will not remove any existing data and is additive in cases where merges occur. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `storeId` | string | yes | An identifier for a store | ### Request body (required) Customer data to import Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/CustomerCreate` ### Responses **202** — A CUSTOMER_CREATE action was successfully created Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/CustomerActionResponse` **401** — Authentication info not sent or is invalid Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` **404** — Resource not found Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` **409** — Application-specific server state error Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` **422** — Body or query string failed schema validation. Returns the `ValidationError` envelope rather than the generic `Error`. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ValidationError` **429** — Too many requests received within interval Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `PAT`; scopes `commerce.customer:create`. # Update customer (https://developer.godaddy.com/en/docs/references/rest/customers/commerce-customers-update) --- title: Update customer description: >- This endpoint can be used to update the information of a specific customer using the store and customer ID. full: true --- ## PATCH /stores/{storeId}/customers/{customerId} Update customer This endpoint can be used to update the information of a specific customer using the store and customer ID. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `customerId` | string | yes | The id of the specific customer | | `storeId` | string | yes | An identifier for a store | ### Request body (required) Customer data to import Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/CustomerUpdate` ### Responses **202** — A CUSTOMER_UPDATE action was successfully created Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/CustomerActionResponse` **401** — Authentication info not sent or is invalid Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` **404** — Resource not found Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` **409** — Application-specific server state error Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` **422** — Body or query string failed schema validation. Returns the `ValidationError` envelope rather than the generic `Error`. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ValidationError` **429** — Too many requests received within interval Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `PAT`; scopes `commerce.customer:update`. # Get customers (https://developer.godaddy.com/en/docs/references/rest/customers/customers-list) --- title: Get customers description: >- This endpoint can be used to retrieve a list of customers for a specific store. full: true --- Full description This endpoint can be used to retrieve a list of customers for a specific store. Deleted customers are excluded by default. ## GET /stores/{storeId}/customers Get customers This endpoint can be used to retrieve a list of customers for a specific store. Deleted customers are excluded by default. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `storeId` | string | yes | An identifier for a store | ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `page` | integer | no | The page of results to return for pagination. Only supported up to the first 10 000 records of a result set. Use pageToken rather than page where possible. PageToken and page can not be used in combination, doing so will result in a 422 response. | | `pageSize` | integer | no | Maximum number of items to return. If used with page will return results with an offset of page * pageSize | | `pageToken` | string | no | Use the `pageToken` returned from a previous search in order to obtain the next set of results. Use pageToken rather than page where possible. PageToken and page can not be used in combination, doing so will result in a 422 response. | | `totalRequired` | boolean | no | Indicates whether the response should include the total number of items and pages through response properties totalItems and totalPages respectively. | | `queryString` | string | no | Search term - this string will be matched as a starts with for all text fields | | `nonEmptyFields` | array | no | Filter customers by presence of at least one of these fields | | `emptyFields` | array | no | Filter customers by absence of at least one of these fields | | `allNonEmptyFields` | array | no | Filter customers by presence of all of these fields | | `allEmptyFields` | array | no | Filter customers by absence of all of these fields | | `externalIdentifiers` | array | no | Filter customers by external identifier; provide as comma separated values in the form `type:value` (eg: `poynt:123,asin:B0B9F7WNQH`) | | `updatedAtStart` | unknown | no | Filter customers whose updatedAt is >= the specified date | | `updatedAtEnd` | unknown | no | Filter customers whose updatedAt is <= the specified date | | `sort` | string | no | Sort expression accepted by the underlying customer search service | | `excludeGuestCustomers` | boolean | no | Whether to exclude guest customers (those without an associated user record). Defaults to true. | ### Responses **200** — Request was successful Content-Type: `application/json` Schema: - allOf(unknown & object) **401** — Authentication info not sent or is invalid Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` **404** — Resource not found Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` **409** — Application-specific server state error Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` **422** — Body or query string failed schema validation. Returns the `ValidationError` envelope rather than the generic `Error`. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ValidationError` **429** — Too many requests received within interval Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `PAT`; scopes `commerce.customer:read`. # Get customer by ID (https://developer.godaddy.com/en/docs/references/rest/customers/fetch-customer) --- title: Get customer by ID description: >- Retrieve the information of a single customer using the store and customer IDs. full: true --- ## GET /stores/{storeId}/customers/{customerId} Get customer by ID Retrieve the information of a single customer using the store and customer IDs. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `customerId` | string | yes | The id of the specific customer | | `storeId` | string | yes | An identifier for a store | ### Responses **200** — Request was successful Content-Type: `application/json` Schema: - object - `customer` (required): unknown - `links` (required): array — HATEOAS link relations - items: **401** — Authentication info not sent or is invalid Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` **404** — Resource not found Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` **422** — Body or query string failed schema validation. Returns the `ValidationError` envelope rather than the generic `Error`. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ValidationError` **429** — Too many requests received within interval Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `PAT`; scopes `commerce.customer:read`. # Domains REST reference (https://developer.godaddy.com/en/docs/references/rest/domains) --- title: Domains REST reference description: >- REST reference for the Domains API. v3 quote-execute registration, plus v1/v2 for DNS, contacts, transfers, and forwarding. --- The complete OpenAPI specs for this namespace are available as JSON — useful for code generation, SDK tooling, and LLM context: [domains-v3.json](https://developer.godaddy.com/openapi/domains-v3.json) (discovery + registration), [domains-v1.json](https://developer.godaddy.com/openapi/domains-v1.json) (account-scoped), and [domains-v2.json](https://developer.godaddy.com/openapi/domains-v2.json) (async operations). The Domains REST API exposes domain availability search, registration, DNS and contact management, registry lock, WHOIS privacy, forwarding, and inbound and outbound transfers. Operations span three version namespaces: `v3` (quote-execute registration model), `v1` (account-scoped), and `v2` (async operation tracking). For a task-shaped guide written for DIY API users, see [Use the API → Domains](https://developer.godaddy.com/docs/api-users/domains/manage). ## The core objects The Domains namespace is built around a small set of resources. Each operation in the reference reads or writes one of these objects. | Object | Description | | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `DomainDetail` (v1) / `DomainDetailV2` (v2) | A registered domain and its registry metadata: name, status, expiration, contacts, nameservers, lock state, and privacy state. | | `DNSRecord` | A single DNS record (`A`, `AAAA`, `CNAME`, `MX`, `TXT`, `SRV`, `NS`, `SOA`, or `CAA`) on a domain that uses GoDaddy's authoritative nameservers. | | `Contact` | A WHOIS contact record covering name, organization, address, email, and phone. The same shape is used for the registrant, admin, billing, and tech roles on a domain. | | `Action` | An asynchronous-operation tracker returned with `202 Accepted` when the API queues a long-running write. Callers poll the action endpoint until the action's `status` reaches a terminal state. | | `DomainAvailableResponse` | The result of an availability check, including the available flag, current price in `currency-micro-unit` format, the registration period in years, and whether the answer is from a live registry call or cache. | | `DomainForwarding` | An HTTP forwarding rule on a domain, configurable as masked or unmasked and as a permanent (`301`) or temporary (`302`) redirect. | | `DomainTransferIn` | The request shape for an inbound transfer, carrying the domain name, authcode, and required contacts. | | `Error` / `ErrorLimit` | The standard error envelope returned on `4xx` and `5xx` responses across the namespace. `ErrorLimit` extends `Error` with `retryAfterSec` for `429` rate-limited responses. | ## Version namespaces ## Conventions used across the namespace | Concern | Where it's documented | | -------------------------------------------------------------- | ------------------------------------------ | | Authentication (PAT for v3; PAT or legacy `sso-key` for v1/v2) | [Authentication](https://developer.godaddy.com/docs/api-users/auth) | | Error envelope and retry semantics | [Errors](https://developer.godaddy.com/docs/api-users/errors) | | Rate limits (60 requests/minute per credential) | [Rate limits](https://developer.godaddy.com/docs/api-users/rate-limits) | | Cursor-based pagination on v1 list endpoints | [Pagination](https://developer.godaddy.com/docs/api-users/pagination) | ## Related references # Check if a mailbox can be provisioned (https://developer.godaddy.com/en/docs/references/rest/email/check-mailbox-eligibility) --- title: Check if a mailbox can be provisioned description: >- Determines whether a mailbox can be provisioned for the given email address and which entitlements are available to use. full: true --- Full description \| Determines whether a mailbox can be provisioned for the given email address and which entitlements are available to use. ## GET /check-mailbox-eligibility Check if a mailbox can be provisioned Determines whether a mailbox can be provisioned for the given email address and which entitlements are available to use. ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `email` | string | yes | Full email address to check (user@domain). | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | string | no | Optional client-generated request correlation identifier. Propagated across services and echoed in the X-Request-Id response header. | ### Responses **200** — Eligibility result for the requested email address. Content-Type: `application/json` ```json { "isEligible": true, "eligibleAccounts": [ { "accountId": "00000000-0000-0000-0000-000000000002", "mailboxType": "TITAN", "accountName": "Professional Email Pro Plus", "default": false, "requirements": [ { "type": "FREETRIAL_AUTORENEW", "title": "Free Trial Auto Renew", "reference": "https://www.godaddy.com/agreements/showdoc?pageid=FREETRIAL_AUTORENEW" } ] } ] } ``` Schema: - schema reference: `#/components/schemas/EligibilityResult` **400** — Malformed request syntax, missing required field, or invalid field value. Content-Type: `application/json` ```json { "name": "INVALID_INPUT", "correlationId": "req-abc-123", "message": "The provided request is invalid.", "details": [ { "field": "/username", "issue": "PATTERN_VIOLATION", "location": "body", "description": "Username must contain only letters, digits, dots, underscores, hyphens, and plus signs.\n" } ] } ``` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication credentials are missing or invalid. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated identity is not authorized to perform this operation. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **422** — The address is not eligible for mailbox provisioning. Check details[] in the response for the specific reason. Content-Type: `application/json` ```json { "name": "ELIGIBILITY_FAILURE", "correlationId": "7f3a9c21-5d84-4e67-b912-3a8f6c2d104e", "message": "Found 1 reason why this email address cannot be provisioned.", "details": [ { "issue": "EMAIL_PLAN_NOT_AVAILABLE", "description": "You need to purchase an email plan to create an email address." } ] } ``` Schema: - schema reference: `#/components/schemas/EligibilityError` **429** — Too many requests — rate limit exceeded. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # Create a new email mailbox (https://developer.godaddy.com/en/docs/references/rest/email/create-mailbox) --- title: Create a new email mailbox description: >- Provisions a new email mailbox for a domain owned by the authenticated account. full: true --- Full description \| Provisions a new email mailbox for a domain owned by the authenticated account. Returns 202 Accepted with the mailbox in its initial state (status: EXECUTING). Poll GET /mailboxes/\{mailboxId} until status reaches COMPLETED or FAILED. ## POST /mailboxes Create a new email mailbox Provisions a new email mailbox for a domain owned by the authenticated account. Returns 202 Accepted with the mailbox in its initial state (status: EXECUTING). Poll GET /mailboxes/{mailboxId} until status reaches COMPLETED or FAILED. ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | string | no | Optional client-generated request correlation identifier. Propagated across services and echoed in the X-Request-Id response header. | | `Idempotency-Key` | string | yes | Client-generated unique key (UUID recommended). Retrying a POST request with the same Idempotency-Key returns the original response without creating a duplicate mailbox. | ### Request body (required) Content-Type: `application/json` ```json { "emailAddress": "jane.smith@example.com", "accountId": "00000000-0000-0000-0000-000000000001", "firstName": "Jane", "lastName": "Smith", "consents": [ { "type": "FREETRIAL_AUTORENEW" } ] } ``` Schema: - object - `emailAddress` (required): string — The full email address for the new mailbox. - `accountId`: string — Entitlement identifier selecting which eligible account/plan to provision the mailbox against (matches EligibleAccount.accountId). - `firstName`: string — First name associated with the mailbox. - `lastName`: string — Last name associated with the mailbox. - `consents`: array — Consent agreements to fulfill at creation time. Required when the selected eligible account has requirements. Each entry must include a type matching a requirement from EligibleAccount.requirements[].type. - items: - `type` (required): string — Requirement type code being consented to. ### Responses **202** — Mailbox provisioning accepted. Content-Type: `application/json` ```json { "mailboxId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "emailAddress": "jane.smith@example.com", "mailboxType": "TITAN", "firstName": "Jane", "lastName": "Smith", "displayName": "Jane Smith", "status": "EXECUTING", "agreements": [ { "type": "FREETRIAL_AUTORENEW", "agreed": true } ], "createdAt": "2024-06-15T12:00:00Z", "updatedAt": "2024-06-15T12:00:00Z", "links": [ { "rel": "self", "href": "/mailboxes/a1b2c3d4-e5f6-7890-abcd-ef1234567890" } ] } ``` Schema: - allOf(unknown & object) **400** — Malformed request syntax, missing required field, or invalid field value. Content-Type: `application/json` ```json { "name": "INVALID_INPUT", "correlationId": "req-abc-123", "message": "The provided request is invalid.", "details": [ { "field": "/username", "issue": "PATTERN_VIOLATION", "location": "body", "description": "Username must contain only letters, digits, dots, underscores, hyphens, and plus signs.\n" } ] } ``` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication credentials are missing or invalid. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated identity is not authorized to perform this operation. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **409** — Conflict — a mailbox with the requested email address already exists for this domain. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **422** — The address is not eligible for mailbox provisioning. Check details[] in the response for the specific reason. Content-Type: `application/json` ```json { "name": "ELIGIBILITY_FAILURE", "correlationId": "7f3a9c21-5d84-4e67-b912-3a8f6c2d104e", "message": "Found 1 reason why this email address cannot be provisioned.", "details": [ { "issue": "EMAIL_PLAN_NOT_AVAILABLE", "description": "You need to purchase an email plan to create an email address." } ] } ``` Schema: - schema reference: `#/components/schemas/EligibilityError` **429** — Too many requests — rate limit exceeded. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # Get a single mailbox by ID (https://developer.godaddy.com/en/docs/references/rest/email/get-mailbox) --- title: Get a single mailbox by ID description: Returns the current state of a single mailbox. full: true --- Full description \| Returns the current state of a single mailbox. Poll this endpoint after POST /mailboxes until status reaches COMPLETED or FAILED. ## GET /mailboxes/{mailboxId} Get a single mailbox by ID Returns the current state of a single mailbox. Poll this endpoint after POST /mailboxes until status reaches COMPLETED or FAILED. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `mailboxId` | string | yes | The mailbox identifier returned from POST /mailboxes. | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | string | no | Optional client-generated request correlation identifier. Propagated across services and echoed in the X-Request-Id response header. | ### Responses **200** — The requested mailbox. Content-Type: `application/json` ```json { "mailboxId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "emailAddress": "jane.smith@example.com", "mailboxType": "TITAN", "firstName": "Jane", "lastName": "Smith", "displayName": "Jane Smith", "status": "COMPLETED", "createdAt": "2024-03-15T10:30:00Z", "updatedAt": "2024-06-01T08:00:00Z", "links": [ { "rel": "self", "href": "/mailboxes/a1b2c3d4-e5f6-7890-abcd-ef1234567890" } ] } ``` Schema: - schema reference: `#/components/schemas/Mailbox` **400** — Malformed request syntax, missing required field, or invalid field value. Content-Type: `application/json` ```json { "name": "INVALID_INPUT", "correlationId": "req-abc-123", "message": "The provided request is invalid.", "details": [ { "field": "/username", "issue": "PATTERN_VIOLATION", "location": "body", "description": "Username must contain only letters, digits, dots, underscores, hyphens, and plus signs.\n" } ] } ``` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication credentials are missing or invalid. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated identity is not authorized to perform this operation. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — The requested resource was not found. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests — rate limit exceeded. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # List all email mailboxes (https://developer.godaddy.com/en/docs/references/rest/email/list-mailboxes) --- title: List all email mailboxes description: >- Returns a paged list of email mailboxes for domains owned by the authenticated account, across all supported email platforms. full: true --- Full description \| Returns a paged list of email mailboxes for domains owned by the authenticated account, across all supported email platforms. ## GET /mailboxes List all email mailboxes Returns a paged list of email mailboxes for domains owned by the authenticated account, across all supported email platforms. ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `status` | unknown | no | Filter mailboxes by operational status. | | `page` | integer | no | Page number (1-based). Defaults to 1. | | `pageSize` | integer | no | Number of mailboxes per page. Defaults to 25, maximum 100. | | `field` | string | no | Comma-separated list of top-level Mailbox fields to include in each response object. When omitted, all fields are returned. | | `totalRequired` | boolean | no | When true, includes totalItems and totalPages in the response body and adds a last navigation link. | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | string | no | Optional client-generated request correlation identifier. Propagated across services and echoed in the X-Request-Id response header. | ### Responses **200** — Paged list of mailboxes. Content-Type: `application/json` ```json { "items": [ { "mailboxId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "emailAddress": "jane.smith@example.com", "mailboxType": "TITAN", "firstName": "Jane", "lastName": "Smith", "displayName": "Jane Smith", "status": "COMPLETED", "createdAt": "2024-03-15T10:30:00Z", "updatedAt": "2024-06-01T08:00:00Z" }, { "mailboxId": "a1b2c3d4-js80-7890-abcd-2kd23459hbsk", "emailAddress": "john.doe@contoso.com", "mailboxType": "TITAN", "firstName": "John", "lastName": "Doe", "displayName": "John Doe", "status": "COMPLETED", "createdAt": "2024-04-10T09:00:00Z", "updatedAt": "2024-06-01T08:00:00Z" } ], "links": [ { "rel": "self", "href": "/mailboxes?page=2&pageSize=25" }, { "rel": "first", "href": "/mailboxes?page=1&pageSize=25" }, { "rel": "next", "href": "/mailboxes?page=3&pageSize=25" }, { "rel": "prev", "href": "/mailboxes?page=1&pageSize=25" } ] } ``` Schema: - schema reference: `#/components/schemas/MailboxList` **400** — Malformed request syntax, missing required field, or invalid field value. Content-Type: `application/json` ```json { "name": "INVALID_INPUT", "correlationId": "req-abc-123", "message": "The provided request is invalid.", "details": [ { "field": "/username", "issue": "PATTERN_VIOLATION", "location": "body", "description": "Username must contain only letters, digits, dots, underscores, hyphens, and plus signs.\n" } ] } ``` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication credentials are missing or invalid. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated identity is not authorized to perform this operation. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests — rate limit exceeded. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # Attach a domain (https://developer.godaddy.com/en/docs/references/rest/hosting/attach-domain) --- title: Attach a domain description: Attaches a custom domain to the application and initiates DNS verification. full: true --- Full description > Attaches a custom domain to the application and initiates DNS verification. Returns `202 Accepted`. Poll `GET /apps/{appId}/domains/{domainId}` until `verificationStatus` is `ACTIVE` or `FAILED`. ## POST /apps/{appId}/domains Attach a domain Attaches a custom domain to the application and initiates DNS verification. Returns `202 Accepted`. Poll `GET /apps/{appId}/domains/{domainId}` until `verificationStatus` is `ACTIVE` or `FAILED`. ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `Idempotency-Key` | string | no | Client-generated UUID that makes a request safe to retry. Supplying the same key on a retry with an identical request body returns the original response without triggering a second operation. Retrying with the same key while the first request is still in flight returns `409 Conflict`. Reusing a key with a different request body returns `422 Unprocessable Entity` with `details[].issue` `IDEMPOTENCY_KEY_MISMATCH`. Keys are retained for 24 hours after the operation completes, after which the key may be reused. | ### Request body (required) Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/AttachDomainRequest` ### Responses **202** — Domain attachment accepted. Poll `links[rel=self]` until `verificationStatus` is `ACTIVE` or `FAILED`. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/7244d8c` **400** — The request body or parameters did not pass schema validation. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication credentials are missing or invalid. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — The caller is authenticated, but the request is not permitted: either the access token does not carry the scope this operation requires, or the operation is disabled for this account. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — The requested resource does not exist. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **409** — The request conflicts with the current state of the resource. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **422** — The request was well-formed but could not be processed due to a business rule violation. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Rate limit exceeded. A `429` response may come in one of two shapes: an empty body with `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` headers; or a JSON `Error` body with `Retry-After` and `RateLimit-*` headers. Clients should honour whichever headers are present and should not assume a JSON body is available on every `429`. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **501** — The request is contract-valid, but the operation, or a value the request names, is not applicable to this deployment. `details[].issue` is always `NOT_APPLICABLE`. For example, deployments and restarts are offered for `NODEJS` applications only, and a hosting product this deployment does not serve is answered here rather than with a `400`. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **503** — The service is temporarily unable to handle the request. Retry after a short delay. May include a `Retry-After` header hinting at when to retry. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # Attach a subscription to an application (https://developer.godaddy.com/en/docs/references/rest/hosting/attach-subscription) --- title: Attach a subscription to an application description: Attaches a hosting subscription to the application. full: true --- Full description > Attaches a hosting subscription to the application. The subscription must have at least one free slot. If not, a `409` is returned with `details[].issue` `NO_CAPACITY`. ## PUT /apps/{appId}/subscription Attach a subscription to an application Attaches a hosting subscription to the application. The subscription must have at least one free slot. If not, a `409` is returned with `details[].issue` `NO_CAPACITY`. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `appId` | string | yes | Application identifier in `{PRODUCT}-{id}` form. The prefix is the application type in upper case — an upper-case letter followed by any number of upper-case letters, digits, or underscores — then a hyphen, then the identifier. For `NODEJS`, the suffix is a 10-character nanoid. Example: `NODEJS-aBcDeFgHiJ`. | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `traceparent` | string | no | W3C Trace Context identifier for this request. Clients should send a `traceparent` on every request so the trace can be correlated across services. See https://www.w3.org/TR/trace-context/ for the format. | ### Request body (required) Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/AttachSubscriptionRequest` ### Responses **200** — Subscription attached. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/896165a` **400** — The request body or parameters did not pass schema validation. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication credentials are missing or invalid. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — The caller is authenticated, but the request is not permitted: either the access token does not carry the scope this operation requires, or the operation is disabled for this account. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — The requested resource does not exist. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **409** — The request conflicts with the current state of the resource. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **422** — The request was well-formed but could not be processed due to a business rule violation. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Rate limit exceeded. A `429` response may come in one of two shapes: an empty body with `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` headers; or a JSON `Error` body with `Retry-After` and `RateLimit-*` headers. Clients should honour whichever headers are present and should not assume a JSON body is available on every `429`. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **501** — The request is contract-valid, but the operation, or a value the request names, is not applicable to this deployment. `details[].issue` is always `NOT_APPLICABLE`. For example, deployments and restarts are offered for `NODEJS` applications only, and a hosting product this deployment does not serve is answered here rather than with a `400`. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **503** — The service is temporarily unable to handle the request. Retry after a short delay. May include a `Retry-After` header hinting at when to retry. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # Restart an application environment (https://developer.godaddy.com/en/docs/references/rest/hosting/create-app-restart) --- title: Restart an application environment description: Triggers a restart of the specified environment (`PREVIEW` or `PUBLISH`). full: true --- Full description > Triggers a restart of the specified environment (`PREVIEW` or `PUBLISH`). Returns `202 Accepted`. Poll `GET /apps/{appId}/status` until the targeted variant reaches a stable state. This endpoint is only applicable to Node.js applications (`appType: NODEJS`): restarts act on the `PREVIEW` and `PUBLISH` environment variants, which are specific to the Node.js runtime model. Other product types return `501`. ## POST /apps/{appId}/restarts Restart an application environment Triggers a restart of the specified environment (`PREVIEW` or `PUBLISH`). Returns `202 Accepted`. Poll `GET /apps/{appId}/status` until the targeted variant reaches a stable state. This endpoint is only applicable to Node.js applications (`appType: NODEJS`): restarts act on the `PREVIEW` and `PUBLISH` environment variants, which are specific to the Node.js runtime model. Other product types return `501`. ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `Idempotency-Key` | string | no | Client-generated UUID that makes a request safe to retry. Supplying the same key on a retry with an identical request body returns the original response without triggering a second operation. Retrying with the same key while the first request is still in flight returns `409 Conflict`. Reusing a key with a different request body returns `422 Unprocessable Entity` with `details[].issue` `IDEMPOTENCY_KEY_MISMATCH`. Keys are retained for 24 hours after the operation completes, after which the key may be reused. | ### Request body (required) Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/RestartRequest` ### Responses **202** — Restart accepted. Poll `links[rel=self]` until the targeted variant reaches a stable state. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/509c3ac` **400** — The request body or parameters did not pass schema validation. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication credentials are missing or invalid. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — The caller is authenticated, but the request is not permitted: either the access token does not carry the scope this operation requires, or the operation is disabled for this account. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — The requested resource does not exist. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **422** — The request was well-formed but could not be processed due to a business rule violation. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Rate limit exceeded. A `429` response may come in one of two shapes: an empty body with `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` headers; or a JSON `Error` body with `Retry-After` and `RateLimit-*` headers. Clients should honour whichever headers are present and should not assume a JSON body is available on every `429`. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **501** — The request is contract-valid, but the operation, or a value the request names, is not applicable to this deployment. `details[].issue` is always `NOT_APPLICABLE`. For example, deployments and restarts are offered for `NODEJS` applications only, and a hosting product this deployment does not serve is answered here rather than with a `400`. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **503** — The service is temporarily unable to handle the request. Retry after a short delay. May include a `Retry-After` header hinting at when to retry. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # Create an application (https://developer.godaddy.com/en/docs/references/rest/hosting/create-app) --- title: Create an application description: Creates a new hosted application. full: true --- Full description > Creates a new hosted application. Because no `appId` exists until provisioning has assigned one, this endpoint returns `202 Accepted` with an `AppOperation` resource carrying an `operationId`. Poll `GET /app-operations/{operationId}` until `status` is `COMPLETED` or `FAILED`. On `COMPLETED` the operation result includes the created `Application` with `status: ACTIVE`; use its `id` for any further calls. Currently only `NODEJS` applications can be created through this endpoint. The request body is product-specific; the fields below apply to Node.js. Support for additional product types will be documented when those paths are available. ## POST /apps Create an application Creates a new hosted application. Because no `appId` exists until provisioning has assigned one, this endpoint returns `202 Accepted` with an `AppOperation` resource carrying an `operationId`. Poll `GET /app-operations/{operationId}` until `status` is `COMPLETED` or `FAILED`. On `COMPLETED` the operation result includes the created `Application` with `status: ACTIVE`; use its `id` for any further calls. Currently only `NODEJS` applications can be created through this endpoint. The request body is product-specific; the fields below apply to Node.js. Support for additional product types will be documented when those paths are available. ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `appType` | unknown | yes | Product type to scope the operation to. | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `Idempotency-Key` | string | no | Client-generated UUID that makes a request safe to retry. Supplying the same key on a retry with an identical request body returns the original response without triggering a second operation. Retrying with the same key while the first request is still in flight returns `409 Conflict`. Reusing a key with a different request body returns `422 Unprocessable Entity` with `details[].issue` `IDEMPOTENCY_KEY_MISMATCH`. Keys are retained for 24 hours after the operation completes, after which the key may be reused. | ### Request body (required) Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/CreateAppRequest` ### Responses **202** — Application creation accepted. Poll `links[rel=self]` until `status` is `COMPLETED` or `FAILED`. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/0bebd09` **400** — The request body or parameters did not pass schema validation. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication credentials are missing or invalid. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — The caller is authenticated, but the request is not permitted: either the access token does not carry the scope this operation requires, or the operation is disabled for this account. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **409** — The request conflicts with the current state of the resource. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **422** — The request was well-formed but could not be processed due to a business rule violation. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Rate limit exceeded. A `429` response may come in one of two shapes: an empty body with `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` headers; or a JSON `Error` body with `Retry-After` and `RateLimit-*` headers. Clients should honour whichever headers are present and should not assume a JSON body is available on every `429`. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **503** — The service is temporarily unable to handle the request. Retry after a short delay. May include a `Retry-After` header hinting at when to retry. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # Trigger a deployment (https://developer.godaddy.com/en/docs/references/rest/hosting/create-deployment) --- title: Trigger a deployment description: Builds the latest imported source and deploys it to the publish environment. full: true --- Full description > Builds the latest imported source and deploys it to the publish environment. Returns `202 Accepted`. Poll `GET /apps/{appId}/deployments/{deploymentId}` until `status` is `COMPLETED` or `FAILED`. This endpoint is only applicable to Node.js applications (`appType: NODEJS`): a deployment builds the imported source and publishes it through the Node.js application agent, which other hosting products do not have. Other product types return `501`. ## POST /apps/{appId}/deployments Trigger a deployment Builds the latest imported source and deploys it to the publish environment. Returns `202 Accepted`. Poll `GET /apps/{appId}/deployments/{deploymentId}` until `status` is `COMPLETED` or `FAILED`. This endpoint is only applicable to Node.js applications (`appType: NODEJS`): a deployment builds the imported source and publishes it through the Node.js application agent, which other hosting products do not have. Other product types return `501`. ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `Idempotency-Key` | string | no | Client-generated UUID that makes a request safe to retry. Supplying the same key on a retry with an identical request body returns the original response without triggering a second operation. Retrying with the same key while the first request is still in flight returns `409 Conflict`. Reusing a key with a different request body returns `422 Unprocessable Entity` with `details[].issue` `IDEMPOTENCY_KEY_MISMATCH`. Keys are retained for 24 hours after the operation completes, after which the key may be reused. | ### Responses **202** — Deployment accepted. Poll `links[rel=self]` until status is terminal. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/edb0cb2` **400** — The request body or parameters did not pass schema validation. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication credentials are missing or invalid. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — The caller is authenticated, but the request is not permitted: either the access token does not carry the scope this operation requires, or the operation is disabled for this account. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — The requested resource does not exist. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **422** — The request was well-formed but could not be processed due to a business rule violation. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Rate limit exceeded. A `429` response may come in one of two shapes: an empty body with `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` headers; or a JSON `Error` body with `Retry-After` and `RateLimit-*` headers. Clients should honour whichever headers are present and should not assume a JSON body is available on every `429`. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **501** — The request is contract-valid, but the operation, or a value the request names, is not applicable to this deployment. `details[].issue` is always `NOT_APPLICABLE`. For example, deployments and restarts are offered for `NODEJS` applications only, and a hosting product this deployment does not serve is answered here rather than with a `400`. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **503** — The service is temporarily unable to handle the request. Retry after a short delay. May include a `Retry-After` header hinting at when to retry. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # Import source code (https://developer.godaddy.com/en/docs/references/rest/hosting/create-source-import) --- title: Import source code description: Imports source code for an application. full: true --- Full description > Imports source code for an application. The `Content-Type` header determines the import type: - `multipart/form-data`: upload a ZIP archive directly. - `application/json`: upload from a connected GitHub repository. Returns `202 Accepted` with a `SourceImport` resource. The `importType` field identifies what was submitted. Poll `GET /apps/{appId}/imports/{importId}` until `status` is `COMPLETED` or `FAILED`. ## POST /apps/{appId}/imports Import source code Imports source code for an application. The `Content-Type` header determines the import type: - `multipart/form-data`: upload a ZIP archive directly. - `application/json`: upload from a connected GitHub repository. Returns `202 Accepted` with a `SourceImport` resource. The `importType` field identifies what was submitted. Poll `GET /apps/{appId}/imports/{importId}` until `status` is `COMPLETED` or `FAILED`. ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `Idempotency-Key` | string | no | Client-generated UUID that makes a request safe to retry. Supplying the same key on a retry with an identical request body returns the original response without triggering a second operation. Retrying with the same key while the first request is still in flight returns `409 Conflict`. Reusing a key with a different request body returns `422 Unprocessable Entity` with `details[].issue` `IDEMPOTENCY_KEY_MISMATCH`. Keys are retained for 24 hours after the operation completes, after which the key may be reused. | ### Request body (required) Content-Type: `multipart/form-data` Schema: - object - `file` (required): string — ZIP archive of the application source code. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ImportGitHubSourceRequest` ### Responses **202** — Import accepted. Poll `links[rel=self]` until status is terminal. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/23e638a` **400** — The request body or parameters did not pass schema validation. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication credentials are missing or invalid. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — The caller is authenticated, but the request is not permitted: either the access token does not carry the scope this operation requires, or the operation is disabled for this account. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — The requested resource does not exist. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **409** — The request conflicts with the current state of the resource. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **422** — The request was well-formed but could not be processed due to a business rule violation. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Rate limit exceeded. A `429` response may come in one of two shapes: an empty body with `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` headers; or a JSON `Error` body with `Retry-After` and `RateLimit-*` headers. Clients should honour whichever headers are present and should not assume a JSON body is available on every `429`. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **501** — The request is contract-valid, but the operation, or a value the request names, is not applicable to this deployment. `details[].issue` is always `NOT_APPLICABLE`. For example, deployments and restarts are offered for `NODEJS` applications only, and a hosting product this deployment does not serve is answered here rather than with a `400`. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **503** — The service is temporarily unable to handle the request. Retry after a short delay. May include a `Retry-After` header hinting at when to retry. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # Delete an application (https://developer.godaddy.com/en/docs/references/rest/hosting/delete-app) --- title: Delete an application description: >- Permanently deletes the application, its deployments, imported source, secrets, and attached domains. full: true --- Full description > Permanently deletes the application, its deployments, imported source, secrets, and attached domains. This action cannot be undone. Returns `204 No Content` on success. ## DELETE /apps/{appId} Delete an application Permanently deletes the application, its deployments, imported source, secrets, and attached domains. This action cannot be undone. Returns `204 No Content` on success. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `appId` | string | yes | Application identifier in `{PRODUCT}-{id}` form. The prefix is the application type in upper case — an upper-case letter followed by any number of upper-case letters, digits, or underscores — then a hyphen, then the identifier. For `NODEJS`, the suffix is a 10-character nanoid. Example: `NODEJS-aBcDeFgHiJ`. | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `traceparent` | string | no | W3C Trace Context identifier for this request. Clients should send a `traceparent` on every request so the trace can be correlated across services. See https://www.w3.org/TR/trace-context/ for the format. | ### Responses **204** — Application deleted. **401** — Authentication credentials are missing or invalid. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — The caller is authenticated, but the request is not permitted: either the access token does not carry the scope this operation requires, or the operation is disabled for this account. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — The requested resource does not exist. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Rate limit exceeded. A `429` response may come in one of two shapes: an empty body with `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` headers; or a JSON `Error` body with `Retry-After` and `RateLimit-*` headers. Clients should honour whichever headers are present and should not assume a JSON body is available on every `429`. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **503** — The service is temporarily unable to handle the request. Retry after a short delay. May include a `Retry-After` header hinting at when to retry. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # Remove a domain attachment (https://developer.godaddy.com/en/docs/references/rest/hosting/detach-domain) --- title: Remove a domain attachment description: Detaches a custom domain from the application. full: true --- Full description > Detaches a custom domain from the application. DNS records at the registrar are not modified. Returns `204 No Content` on success. ## DELETE /apps/{appId}/domains/{domainId} Remove a domain attachment Detaches a custom domain from the application. DNS records at the registrar are not modified. Returns `204 No Content` on success. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `appId` | string | yes | Application identifier in `{PRODUCT}-{id}` form. The prefix is the application type in upper case — an upper-case letter followed by any number of upper-case letters, digits, or underscores — then a hyphen, then the identifier. For `NODEJS`, the suffix is a 10-character nanoid. Example: `NODEJS-aBcDeFgHiJ`. | | `domainId` | string | yes | Domain attachment identifier returned in the `domainId` field of `POST /apps/{appId}/domains`. | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `traceparent` | string | no | W3C Trace Context identifier for this request. Clients should send a `traceparent` on every request so the trace can be correlated across services. See https://www.w3.org/TR/trace-context/ for the format. | ### Responses **204** — Domain detached. **401** — Authentication credentials are missing or invalid. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — The caller is authenticated, but the request is not permitted: either the access token does not carry the scope this operation requires, or the operation is disabled for this account. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — The requested resource does not exist. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Rate limit exceeded. A `429` response may come in one of two shapes: an empty body with `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` headers; or a JSON `Error` body with `Retry-After` and `RateLimit-*` headers. Clients should honour whichever headers are present and should not assume a JSON body is available on every `429`. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **501** — The request is contract-valid, but the operation, or a value the request names, is not applicable to this deployment. `details[].issue` is always `NOT_APPLICABLE`. For example, deployments and restarts are offered for `NODEJS` applications only, and a hosting product this deployment does not serve is answered here rather than with a `400`. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **503** — The service is temporarily unable to handle the request. Retry after a short delay. May include a `Retry-After` header hinting at when to retry. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # Get an application-creation operation (https://developer.godaddy.com/en/docs/references/rest/hosting/get-app-operation) --- title: Get an application-creation operation description: Returns the current state of an application-creation operation. full: true --- Full description > Returns the current state of an application-creation operation. Use this as the poll target after `POST /apps` until `status` reaches `COMPLETED` or `FAILED`. On `COMPLETED`, the response includes the created `Application` with `status: ACTIVE`. ## GET /app-operations/{operationId} Get an application-creation operation Returns the current state of an application-creation operation. Use this as the poll target after `POST /apps` until `status` reaches `COMPLETED` or `FAILED`. On `COMPLETED`, the response includes the created `Application` with `status: ACTIVE`. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `operationId` | string | yes | The operation identifier returned by `POST /apps`. | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `traceparent` | string | no | W3C Trace Context identifier for this request. Clients should send a `traceparent` on every request so the trace can be correlated across services. See https://www.w3.org/TR/trace-context/ for the format. | ### Responses **200** — Operation details. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/0bebd09` **401** — Authentication credentials are missing or invalid. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — The caller is authenticated, but the request is not permitted: either the access token does not carry the scope this operation requires, or the operation is disabled for this account. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — The requested resource does not exist. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Rate limit exceeded. A `429` response may come in one of two shapes: an empty body with `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` headers; or a JSON `Error` body with `Retry-After` and `RateLimit-*` headers. Clients should honour whichever headers are present and should not assume a JSON body is available on every `429`. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **503** — The service is temporarily unable to handle the request. Retry after a short delay. May include a `Retry-After` header hinting at when to retry. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # Get application runtime status (https://developer.godaddy.com/en/docs/references/rest/hosting/get-app-status) --- title: Get application runtime status description: Returns per-environment lifecycle detail. full: true --- Full description > Returns per-environment lifecycle detail. Use as the poll target after `POST /apps/{appId}/restarts`. ## GET /apps/{appId}/status Get application runtime status Returns per-environment lifecycle detail. Use as the poll target after `POST /apps/{appId}/restarts`. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `appId` | string | yes | Application identifier in `{PRODUCT}-{id}` form. The prefix is the application type in upper case — an upper-case letter followed by any number of upper-case letters, digits, or underscores — then a hyphen, then the identifier. For `NODEJS`, the suffix is a 10-character nanoid. Example: `NODEJS-aBcDeFgHiJ`. | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `traceparent` | string | no | W3C Trace Context identifier for this request. Clients should send a `traceparent` on every request so the trace can be correlated across services. See https://www.w3.org/TR/trace-context/ for the format. | ### Responses **200** — Application status. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/509c3ac` **401** — Authentication credentials are missing or invalid. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — The caller is authenticated, but the request is not permitted: either the access token does not carry the scope this operation requires, or the operation is disabled for this account. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — The requested resource does not exist. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Rate limit exceeded. A `429` response may come in one of two shapes: an empty body with `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` headers; or a JSON `Error` body with `Retry-After` and `RateLimit-*` headers. Clients should honour whichever headers are present and should not assume a JSON body is available on every `429`. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **501** — The request is contract-valid, but the operation, or a value the request names, is not applicable to this deployment. `details[].issue` is always `NOT_APPLICABLE`. For example, deployments and restarts are offered for `NODEJS` applications only, and a hosting product this deployment does not serve is answered here rather than with a `400`. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **503** — The service is temporarily unable to handle the request. Retry after a short delay. May include a `Retry-After` header hinting at when to retry. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # Get an application (https://developer.godaddy.com/en/docs/references/rest/hosting/get-app) --- title: Get an application description: Returns the current state of an application. full: true --- Full description \| Returns the current state of an application. ## GET /apps/{appId} Get an application Returns the current state of an application. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `appId` | string | yes | Application identifier in `{PRODUCT}-{id}` form. The prefix is the application type in upper case — an upper-case letter followed by any number of upper-case letters, digits, or underscores — then a hyphen, then the identifier. For `NODEJS`, the suffix is a 10-character nanoid. Example: `NODEJS-aBcDeFgHiJ`. | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `traceparent` | string | no | W3C Trace Context identifier for this request. Clients should send a `traceparent` on every request so the trace can be correlated across services. See https://www.w3.org/TR/trace-context/ for the format. | ### Responses **200** — Application details. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/a87153c` **401** — Authentication credentials are missing or invalid. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — The caller is authenticated, but the request is not permitted: either the access token does not carry the scope this operation requires, or the operation is disabled for this account. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — The requested resource does not exist. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Rate limit exceeded. A `429` response may come in one of two shapes: an empty body with `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` headers; or a JSON `Error` body with `Retry-After` and `RateLimit-*` headers. Clients should honour whichever headers are present and should not assume a JSON body is available on every `429`. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **503** — The service is temporarily unable to handle the request. Retry after a short delay. May include a `Retry-After` header hinting at when to retry. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # Get deployment build logs (https://developer.godaddy.com/en/docs/references/rest/hosting/get-deployment-logs) --- title: Get deployment build logs description: >- Returns the full build and publish log stream captured for a deployment, as an ordered array of opaque lines. full: true --- Full description > Returns the full build and publish log stream captured for a deployment, as an ordered array of opaque lines. `Deployment.logs` carries the same lines when they are available on the deployment itself; this operation is the canonical source and is safe to call while the deployment is still in progress. These are builder logs. Logs emitted by the running application are read from `GET /apps/{appId}/logs`, which returns structured `LogEntry` objects instead. ## GET /apps/{appId}/deployments/{deploymentId}/logs Get deployment build logs Returns the full build and publish log stream captured for a deployment, as an ordered array of opaque lines. `Deployment.logs` carries the same lines when they are available on the deployment itself; this operation is the canonical source and is safe to call while the deployment is still in progress. These are builder logs. Logs emitted by the running application are read from `GET /apps/{appId}/logs`, which returns structured `LogEntry` objects instead. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `appId` | string | yes | Application identifier in `{PRODUCT}-{id}` form. The prefix is the application type in upper case — an upper-case letter followed by any number of upper-case letters, digits, or underscores — then a hyphen, then the identifier. For `NODEJS`, the suffix is a 10-character nanoid. Example: `NODEJS-aBcDeFgHiJ`. | | `deploymentId` | string | yes | Deployment identifier returned in the `deploymentId` field of `POST /apps/{appId}/deployments`. | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `traceparent` | string | no | W3C Trace Context identifier for this request. Clients should send a `traceparent` on every request so the trace can be correlated across services. See https://www.w3.org/TR/trace-context/ for the format. | ### Responses **200** — Full log stream for the deployment. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/eb8fc65` **401** — Authentication credentials are missing or invalid. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — The caller is authenticated, but the request is not permitted: either the access token does not carry the scope this operation requires, or the operation is disabled for this account. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — The requested resource does not exist. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Rate limit exceeded. A `429` response may come in one of two shapes: an empty body with `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` headers; or a JSON `Error` body with `Retry-After` and `RateLimit-*` headers. Clients should honour whichever headers are present and should not assume a JSON body is available on every `429`. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **501** — The request is contract-valid, but the operation, or a value the request names, is not applicable to this deployment. `details[].issue` is always `NOT_APPLICABLE`. For example, deployments and restarts are offered for `NODEJS` applications only, and a hosting product this deployment does not serve is answered here rather than with a `400`. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **503** — The service is temporarily unable to handle the request. Retry after a short delay. May include a `Retry-After` header hinting at when to retry. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # Get a deployment (https://developer.godaddy.com/en/docs/references/rest/hosting/get-deployment) --- title: Get a deployment description: Returns the current state of a deployment. full: true --- Full description > Returns the current state of a deployment. Use as the poll target after `POST /apps/{appId}/deployments` until `status` reaches `COMPLETED` or `FAILED`. ## GET /apps/{appId}/deployments/{deploymentId} Get a deployment Returns the current state of a deployment. Use as the poll target after `POST /apps/{appId}/deployments` until `status` reaches `COMPLETED` or `FAILED`. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `appId` | string | yes | Application identifier in `{PRODUCT}-{id}` form. The prefix is the application type in upper case — an upper-case letter followed by any number of upper-case letters, digits, or underscores — then a hyphen, then the identifier. For `NODEJS`, the suffix is a 10-character nanoid. Example: `NODEJS-aBcDeFgHiJ`. | | `deploymentId` | string | yes | Deployment identifier returned in the `deploymentId` field of `POST /apps/{appId}/deployments`. | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `traceparent` | string | no | W3C Trace Context identifier for this request. Clients should send a `traceparent` on every request so the trace can be correlated across services. See https://www.w3.org/TR/trace-context/ for the format. | ### Responses **200** — Deployment details. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/edb0cb2` **401** — Authentication credentials are missing or invalid. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — The caller is authenticated, but the request is not permitted: either the access token does not carry the scope this operation requires, or the operation is disabled for this account. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — The requested resource does not exist. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Rate limit exceeded. A `429` response may come in one of two shapes: an empty body with `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` headers; or a JSON `Error` body with `Retry-After` and `RateLimit-*` headers. Clients should honour whichever headers are present and should not assume a JSON body is available on every `429`. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **501** — The request is contract-valid, but the operation, or a value the request names, is not applicable to this deployment. `details[].issue` is always `NOT_APPLICABLE`. For example, deployments and restarts are offered for `NODEJS` applications only, and a hosting product this deployment does not serve is answered here rather than with a `400`. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **503** — The service is temporarily unable to handle the request. Retry after a short delay. May include a `Retry-After` header hinting at when to retry. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # Get a domain attachment (https://developer.godaddy.com/en/docs/references/rest/hosting/get-domain) --- title: Get a domain attachment description: >- Returns the current state of a domain attachment, including `verificationStatus`. full: true --- Full description > Returns the current state of a domain attachment, including `verificationStatus`. Use as the poll target after `POST /apps/{appId}/domains`. ## GET /apps/{appId}/domains/{domainId} Get a domain attachment Returns the current state of a domain attachment, including `verificationStatus`. Use as the poll target after `POST /apps/{appId}/domains`. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `appId` | string | yes | Application identifier in `{PRODUCT}-{id}` form. The prefix is the application type in upper case — an upper-case letter followed by any number of upper-case letters, digits, or underscores — then a hyphen, then the identifier. For `NODEJS`, the suffix is a 10-character nanoid. Example: `NODEJS-aBcDeFgHiJ`. | | `domainId` | string | yes | Domain attachment identifier returned in the `domainId` field of `POST /apps/{appId}/domains`. | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `traceparent` | string | no | W3C Trace Context identifier for this request. Clients should send a `traceparent` on every request so the trace can be correlated across services. See https://www.w3.org/TR/trace-context/ for the format. | ### Responses **200** — Domain attachment details. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/7244d8c` **401** — Authentication credentials are missing or invalid. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — The caller is authenticated, but the request is not permitted: either the access token does not carry the scope this operation requires, or the operation is disabled for this account. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — The requested resource does not exist. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Rate limit exceeded. A `429` response may come in one of two shapes: an empty body with `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` headers; or a JSON `Error` body with `Retry-After` and `RateLimit-*` headers. Clients should honour whichever headers are present and should not assume a JSON body is available on every `429`. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **501** — The request is contract-valid, but the operation, or a value the request names, is not applicable to this deployment. `details[].issue` is always `NOT_APPLICABLE`. For example, deployments and restarts are offered for `NODEJS` applications only, and a hosting product this deployment does not serve is answered here rather than with a `400`. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **503** — The service is temporarily unable to handle the request. Retry after a short delay. May include a `Retry-After` header hinting at when to retry. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # Get application logs (https://developer.godaddy.com/en/docs/references/rest/hosting/get-logs) --- title: Get application logs description: 'Returns log entries for the application, newest first.' full: true --- Full description > Returns log entries for the application, newest first. The v2 endpoint always returns entries in the normalized shape defined by `LogEntry`: `timestamp`, `level` (`INFO`/`WARN`/`ERROR`), `source` (`STDOUT`/`STDERR`), and `message`. Entries whose raw level or source cannot be mapped to one of the values defined today are dropped, so no entry is returned carrying a value outside `LogLevel` or `LogSource`. Both enumerations may gain members in a future version of this specification, so clients must not fail on a value they do not recognise. `variant` selects the environment (`PREVIEW` or `PUBLISH`), matching the `variant` field used by the restart request body. The service still honours two earlier spellings, `target` and `environment`, both deprecated; the precedence is `variant` > `target` > `environment`, and the first one supplied wins while the others are ignored. When none is supplied the environment defaults to `PREVIEW`. New clients should send `variant` only. `since` limits results to entries at or after the given timestamp; defaults to 24 hours ago and cannot exceed 7 days. `level` filters entries by severity after retrieval. ## GET /apps/{appId}/logs Get application logs Returns log entries for the application, newest first. The v2 endpoint always returns entries in the normalized shape defined by `LogEntry`: `timestamp`, `level` (`INFO`/`WARN`/`ERROR`), `source` (`STDOUT`/`STDERR`), and `message`. Entries whose raw level or source cannot be mapped to one of the values defined today are dropped, so no entry is returned carrying a value outside `LogLevel` or `LogSource`. Both enumerations may gain members in a future version of this specification, so clients must not fail on a value they do not recognise. `variant` selects the environment (`PREVIEW` or `PUBLISH`), matching the `variant` field used by the restart request body. The service still honours two earlier spellings, `target` and `environment`, both deprecated; the precedence is `variant` > `target` > `environment`, and the first one supplied wins while the others are ignored. When none is supplied the environment defaults to `PREVIEW`. New clients should send `variant` only. `since` limits results to entries at or after the given timestamp; defaults to 24 hours ago and cannot exceed 7 days. `level` filters entries by severity after retrieval. ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `variant` | unknown | no | Environment to retrieve logs from. The canonical parameter; it takes precedence over the deprecated `target` and `environment`. Defaults to `PREVIEW` when none of the three is supplied. | | `since` | unknown | no | Return only entries at or after this ISO 8601 timestamp (must include timezone offset). Defaults to 24 hours ago. Cannot exceed 7 days in the past. | | `source` | unknown | no | Filter logs by source stream. Defaults to all streams. | | `level` | unknown | no | Filter logs by severity level. | | `pageToken` | unknown | no | Opaque pagination cursor. Clients should navigate by following `links[rel=next].href` from the previous response rather than constructing URLs manually; this parameter is documented so that the endpoint's contract is discoverable. | | `pageSize` | integer | no | Maximum number of log entries to return. | ### Responses **200** — Log entries, newest first. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/PagedLogEntries` **400** — The request body or parameters did not pass schema validation. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication credentials are missing or invalid. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — The caller is authenticated, but the request is not permitted: either the access token does not carry the scope this operation requires, or the operation is disabled for this account. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — The requested resource does not exist. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Rate limit exceeded. A `429` response may come in one of two shapes: an empty body with `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` headers; or a JSON `Error` body with `Retry-After` and `RateLimit-*` headers. Clients should honour whichever headers are present and should not assume a JSON body is available on every `429`. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **501** — The request is contract-valid, but the operation, or a value the request names, is not applicable to this deployment. `details[].issue` is always `NOT_APPLICABLE`. For example, deployments and restarts are offered for `NODEJS` applications only, and a hosting product this deployment does not serve is answered here rather than with a `400`. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **503** — The service is temporarily unable to handle the request. Retry after a short delay. May include a `Retry-After` header hinting at when to retry. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # Get runtime configuration (https://developer.godaddy.com/en/docs/references/rest/hosting/get-runtime) --- title: Get runtime configuration description: Returns the runtime version configuration for the application. full: true --- Full description > Returns the runtime version configuration for the application. Each entry identifies a runtime component (e.g. `NODE`, `PHP`, `WORDPRESS`) and its current version. ## GET /apps/{appId}/runtime Get runtime configuration Returns the runtime version configuration for the application. Each entry identifies a runtime component (e.g. `NODE`, `PHP`, `WORDPRESS`) and its current version. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `appId` | string | yes | Application identifier in `{PRODUCT}-{id}` form. The prefix is the application type in upper case — an upper-case letter followed by any number of upper-case letters, digits, or underscores — then a hyphen, then the identifier. For `NODEJS`, the suffix is a 10-character nanoid. Example: `NODEJS-aBcDeFgHiJ`. | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `traceparent` | string | no | W3C Trace Context identifier for this request. Clients should send a `traceparent` on every request so the trace can be correlated across services. See https://www.w3.org/TR/trace-context/ for the format. | ### Responses **200** — Runtime version configuration for the application. Content-Type: `application/json` Schema: - array - items: **401** — Authentication credentials are missing or invalid. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — The caller is authenticated, but the request is not permitted: either the access token does not carry the scope this operation requires, or the operation is disabled for this account. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — The requested resource does not exist. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Rate limit exceeded. A `429` response may come in one of two shapes: an empty body with `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` headers; or a JSON `Error` body with `Retry-After` and `RateLimit-*` headers. Clients should honour whichever headers are present and should not assume a JSON body is available on every `429`. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **503** — The service is temporarily unable to handle the request. Retry after a short delay. May include a `Retry-After` header hinting at when to retry. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # Get a source import (https://developer.godaddy.com/en/docs/references/rest/hosting/get-source-import) --- title: Get a source import description: Returns the current state of a source import. full: true --- Full description > Returns the current state of a source import. Use as the poll target after `POST /apps/{appId}/imports` until `status` reaches `COMPLETED` or `FAILED`. ## GET /apps/{appId}/imports/{importId} Get a source import Returns the current state of a source import. Use as the poll target after `POST /apps/{appId}/imports` until `status` reaches `COMPLETED` or `FAILED`. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `appId` | string | yes | Application identifier in `{PRODUCT}-{id}` form. The prefix is the application type in upper case — an upper-case letter followed by any number of upper-case letters, digits, or underscores — then a hyphen, then the identifier. For `NODEJS`, the suffix is a 10-character nanoid. Example: `NODEJS-aBcDeFgHiJ`. | | `importId` | string | yes | Import identifier returned in the `importId` field of `POST /apps/{appId}/imports`. | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `traceparent` | string | no | W3C Trace Context identifier for this request. Clients should send a `traceparent` on every request so the trace can be correlated across services. See https://www.w3.org/TR/trace-context/ for the format. | ### Responses **200** — Source import details. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/23e638a` **401** — Authentication credentials are missing or invalid. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — The caller is authenticated, but the request is not permitted: either the access token does not carry the scope this operation requires, or the operation is disabled for this account. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — The requested resource does not exist. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Rate limit exceeded. A `429` response may come in one of two shapes: an empty body with `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` headers; or a JSON `Error` body with `Retry-After` and `RateLimit-*` headers. Clients should honour whichever headers are present and should not assume a JSON body is available on every `429`. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **501** — The request is contract-valid, but the operation, or a value the request names, is not applicable to this deployment. `details[].issue` is always `NOT_APPLICABLE`. For example, deployments and restarts are offered for `NODEJS` applications only, and a hosting product this deployment does not serve is answered here rather than with a `400`. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **503** — The service is temporarily unable to handle the request. Retry after a short delay. May include a `Retry-After` header hinting at when to retry. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # Get the subscription attached to an application (https://developer.godaddy.com/en/docs/references/rest/hosting/get-subscription-attachment) --- title: Get the subscription attached to an application description: Returns the subscription currently attached to this application. full: true --- Full description > Returns the subscription currently attached to this application. Returns `404` if no subscription has ever been attached. ## GET /apps/{appId}/subscription Get the subscription attached to an application Returns the subscription currently attached to this application. Returns `404` if no subscription has ever been attached. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `appId` | string | yes | Application identifier in `{PRODUCT}-{id}` form. The prefix is the application type in upper case — an upper-case letter followed by any number of upper-case letters, digits, or underscores — then a hyphen, then the identifier. For `NODEJS`, the suffix is a 10-character nanoid. Example: `NODEJS-aBcDeFgHiJ`. | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `traceparent` | string | no | W3C Trace Context identifier for this request. Clients should send a `traceparent` on every request so the trace can be correlated across services. See https://www.w3.org/TR/trace-context/ for the format. | ### Responses **200** — Current subscription attachment. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/896165a` **401** — Authentication credentials are missing or invalid. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — The caller is authenticated, but the request is not permitted: either the access token does not carry the scope this operation requires, or the operation is disabled for this account. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — The requested resource does not exist. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Rate limit exceeded. A `429` response may come in one of two shapes: an empty body with `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` headers; or a JSON `Error` body with `Retry-After` and `RateLimit-*` headers. Clients should honour whichever headers are present and should not assume a JSON body is available on every `429`. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **501** — The request is contract-valid, but the operation, or a value the request names, is not applicable to this deployment. `details[].issue` is always `NOT_APPLICABLE`. For example, deployments and restarts are offered for `NODEJS` applications only, and a hosting product this deployment does not serve is answered here rather than with a `400`. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **503** — The service is temporarily unable to handle the request. Retry after a short delay. May include a `Retry-After` header hinting at when to retry. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # Overview (https://developer.godaddy.com/en/docs/references/rest/hosting) --- title: Overview description: > Reference for the Hosting API, a REST API for deploying and operating GoDaddy hosted applications. Async-first: long-running writes return immediately with a job or deployment record you poll to completion. Currently supports Node.js apps. --- The complete OpenAPI spec for this namespace is available as JSON. This is useful for code generation, SDK tooling, and LLM context: [hosting.json](https://developer.godaddy.com/openapi/hosting.json). ## Overview The Hosting API lets you build, deploy, and operate apps on GoDaddy's hosting platform without touching a dashboard. Each app has two variants (`preview` and `publish`) so you can iterate safely and promote when you're ready. The API supports Node.js apps. Long-running operations (create app, upload source, publish) return immediately with a job or deployment record. All three respond with `202 Accepted`. Poll until each operation reaches a terminal state. Go to [Hosting concepts](https://developer.godaddy.com/docs/api-users/hosting/concepts) for the full pattern. Every endpoint authenticates with a Personal Access Token (PAT). Create one at [Personal Access Tokens](https://developer.godaddy.com/personal-access-token), send it as `Authorization: Bearer `, and select only the scopes each operation requires. Go to [Hosting core concepts](https://developer.godaddy.com/docs/api-users/hosting/concepts#scopes-reference) for the full scope list. ## Endpoint groups ## Typical flow ``` POST /apps?appType=NODEJS → 202, AppOperation GET /app-operations/{operationId} → poll until app is ready POST /apps/{appId}/imports → 202, SourceImport operation (multipart/form-data) GET /apps/{appId}/imports/{importId} → poll until upload is processed PUT /apps/{appId}/subscription → 200, attach to hosting plan (required for Node.js) POST /apps/{appId}/deployments → 202, Deployment operation GET /apps/{appId}/deployments/{id} → poll until deployment is complete GET /apps/{appId}/status → runtime status per environment ``` ## Conventions | Convention | Detail | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Base URL | `https://api.godaddy.com/v1/hosting` (production) | | Async operations | Create app, import source, and deploy operations return `202 Accepted` with an operation. Poll the returned URL until status reaches `COMPLETED` or `FAILED`. | | Environments | Every app has `PREVIEW` and `PUBLISH` environments. Filter per endpoint: `/logs?target=…`, `/secrets` (body `variant`). `/status` returns both. | | Auth | Personal Access Token (PAT) — `Authorization: Bearer `. Go to [Hosting core concepts](https://developer.godaddy.com/docs/api-users/hosting/concepts#scopes-reference) for the scope list. | | Secret values | Never returned by any endpoint. Only names and metadata are readable. | | Rate limits | Enforced by the API gateway. `429 Too Many Requests` response includes `RateLimit-*` headers. | # List applications (https://developer.godaddy.com/en/docs/references/rest/hosting/list-apps) --- title: List applications description: Returns a paginated list of applications for the authenticated user. full: true --- Full description > Returns a paginated list of applications for the authenticated user. `appType` is required. Cross-product listing will be supported in a future version. ## GET /apps List applications Returns a paginated list of applications for the authenticated user. `appType` is required. Cross-product listing will be supported in a future version. ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `appType` | unknown | yes | Product type to scope the operation to. | | `pageToken` | unknown | no | Opaque pagination cursor. Clients should navigate by following `links[rel=next].href` from the previous response rather than constructing URLs manually; this parameter is documented so that the endpoint's contract is discoverable. | | `pageSize` | unknown | no | Maximum number of items to return. | | `totalRequired` | unknown | no | When `true`, populate `totalItems` in the response. This may impact response time on large collections. | ### Responses **200** — Paginated list of applications. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/PagedApplications` **400** — The request body or parameters did not pass schema validation. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication credentials are missing or invalid. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — The caller is authenticated, but the request is not permitted: either the access token does not carry the scope this operation requires, or the operation is disabled for this account. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Rate limit exceeded. A `429` response may come in one of two shapes: an empty body with `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` headers; or a JSON `Error` body with `Retry-After` and `RateLimit-*` headers. Clients should honour whichever headers are present and should not assume a JSON body is available on every `429`. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **503** — The service is temporarily unable to handle the request. Retry after a short delay. May include a `Retry-After` header hinting at when to retry. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # List deployments (https://developer.godaddy.com/en/docs/references/rest/hosting/list-deployments) --- title: List deployments description: 'Returns deployments for the application, newest first.' full: true --- Full description > Returns deployments for the application, newest first. Use this to inspect deployment history or find the most recent successful build. ## GET /apps/{appId}/deployments List deployments Returns deployments for the application, newest first. Use this to inspect deployment history or find the most recent successful build. ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `pageToken` | unknown | no | Opaque pagination cursor. Clients should navigate by following `links[rel=next].href` from the previous response rather than constructing URLs manually; this parameter is documented so that the endpoint's contract is discoverable. | | `pageSize` | unknown | no | Maximum number of items to return. | | `totalRequired` | unknown | no | When `true`, populate `totalItems` in the response. This may impact response time on large collections. | ### Responses **200** — Paginated list of deployments, newest first. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/PagedDeployments` **401** — Authentication credentials are missing or invalid. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — The caller is authenticated, but the request is not permitted: either the access token does not carry the scope this operation requires, or the operation is disabled for this account. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — The requested resource does not exist. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Rate limit exceeded. A `429` response may come in one of two shapes: an empty body with `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` headers; or a JSON `Error` body with `Retry-After` and `RateLimit-*` headers. Clients should honour whichever headers are present and should not assume a JSON body is available on every `429`. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **501** — The request is contract-valid, but the operation, or a value the request names, is not applicable to this deployment. `details[].issue` is always `NOT_APPLICABLE`. For example, deployments and restarts are offered for `NODEJS` applications only, and a hosting product this deployment does not serve is answered here rather than with a `400`. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **503** — The service is temporarily unable to handle the request. Retry after a short delay. May include a `Retry-After` header hinting at when to retry. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # List attached domains (https://developer.godaddy.com/en/docs/references/rest/hosting/list-domains) --- title: List attached domains description: >- Returns the domains currently attached to this application, including their DNS verification state. full: true --- Full description > Returns the domains currently attached to this application, including their DNS verification state. ## GET /apps/{appId}/domains List attached domains Returns the domains currently attached to this application, including their DNS verification state. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `appId` | string | yes | Application identifier in `{PRODUCT}-{id}` form. The prefix is the application type in upper case — an upper-case letter followed by any number of upper-case letters, digits, or underscores — then a hyphen, then the identifier. For `NODEJS`, the suffix is a 10-character nanoid. Example: `NODEJS-aBcDeFgHiJ`. | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `traceparent` | string | no | W3C Trace Context identifier for this request. Clients should send a `traceparent` on every request so the trace can be correlated across services. See https://www.w3.org/TR/trace-context/ for the format. | ### Responses **200** — Domains attached to this application. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/PagedDomains` **401** — Authentication credentials are missing or invalid. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — The caller is authenticated, but the request is not permitted: either the access token does not carry the scope this operation requires, or the operation is disabled for this account. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — The requested resource does not exist. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Rate limit exceeded. A `429` response may come in one of two shapes: an empty body with `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` headers; or a JSON `Error` body with `Retry-After` and `RateLimit-*` headers. Clients should honour whichever headers are present and should not assume a JSON body is available on every `429`. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **501** — The request is contract-valid, but the operation, or a value the request names, is not applicable to this deployment. `details[].issue` is always `NOT_APPLICABLE`. For example, deployments and restarts are offered for `NODEJS` applications only, and a hosting product this deployment does not serve is answered here rather than with a `400`. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **503** — The service is temporarily unable to handle the request. Retry after a short delay. May include a `Retry-After` header hinting at when to retry. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # List secrets (https://developer.godaddy.com/en/docs/references/rest/hosting/list-secrets) --- title: List secrets description: Returns secret metadata. full: true --- Full description \| Returns secret metadata. Values are never included in responses. ## GET /apps/{appId}/secrets List secrets Returns secret metadata. Values are never included in responses. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `appId` | string | yes | Application identifier in `{PRODUCT}-{id}` form. The prefix is the application type in upper case — an upper-case letter followed by any number of upper-case letters, digits, or underscores — then a hyphen, then the identifier. For `NODEJS`, the suffix is a 10-character nanoid. Example: `NODEJS-aBcDeFgHiJ`. | ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `variant` | unknown | no | The environment variant to target. Defaults to `PREVIEW`. | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `traceparent` | string | no | W3C Trace Context identifier for this request. Clients should send a `traceparent` on every request so the trace can be correlated across services. See https://www.w3.org/TR/trace-context/ for the format. | ### Responses **200** — Secret metadata list. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/SecretList` **401** — Authentication credentials are missing or invalid. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — The caller is authenticated, but the request is not permitted: either the access token does not carry the scope this operation requires, or the operation is disabled for this account. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — The requested resource does not exist. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Rate limit exceeded. A `429` response may come in one of two shapes: an empty body with `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` headers; or a JSON `Error` body with `Retry-After` and `RateLimit-*` headers. Clients should honour whichever headers are present and should not assume a JSON body is available on every `429`. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **501** — The request is contract-valid, but the operation, or a value the request names, is not applicable to this deployment. `details[].issue` is always `NOT_APPLICABLE`. For example, deployments and restarts are offered for `NODEJS` applications only, and a hosting product this deployment does not serve is answered here rather than with a `400`. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **503** — The service is temporarily unable to handle the request. Retry after a short delay. May include a `Retry-After` header hinting at when to retry. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # List hosting subscriptions (https://developer.godaddy.com/en/docs/references/rest/hosting/list-subscriptions) --- title: List hosting subscriptions description: >- Returns hosting subscriptions for the authenticated user, including slot usage. full: true --- Full description > Returns hosting subscriptions for the authenticated user, including slot usage. Use this to find a `subscriptionId` when attaching a subscription to an application. `hostingProduct` is required. Cross-product listing will be supported in a future version. The parameter has three outcomes. Omitting it, or sending a value outside `HostingProduct`, returns `400` with `details[].issue` `VALIDATION_FAILED`. Sending a product the enum admits but this deployment does not serve returns `501` with `details[].issue` `NOT_APPLICABLE` — never `400`. Sending a product this deployment serves returns `200`. ## GET /subscriptions List hosting subscriptions Returns hosting subscriptions for the authenticated user, including slot usage. Use this to find a `subscriptionId` when attaching a subscription to an application. `hostingProduct` is required. Cross-product listing will be supported in a future version. The parameter has three outcomes. Omitting it, or sending a value outside `HostingProduct`, returns `400` with `details[].issue` `VALIDATION_FAILED`. Sending a product the enum admits but this deployment does not serve returns `501` with `details[].issue` `NOT_APPLICABLE` — never `400`. Sending a product this deployment serves returns `200`. ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `hostingProduct` | unknown | yes | Hosting product to scope the operation to. This filter is required rather than optional: an optional filter introduced after general availability would have to default to `WEB_HOSTING` for ever, or the set of subscriptions returned would silently change for clients that omit it. It is made required now, while this spec is still Beta. | ### Responses **200** — Hosting subscriptions. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/PagedSubscriptions` **400** — The request body or parameters did not pass schema validation. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication credentials are missing or invalid. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — The caller is authenticated, but the request is not permitted: either the access token does not carry the scope this operation requires, or the operation is disabled for this account. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Rate limit exceeded. A `429` response may come in one of two shapes: an empty body with `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` headers; or a JSON `Error` body with `Retry-After` and `RateLimit-*` headers. Clients should honour whichever headers are present and should not assume a JSON body is available on every `429`. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **501** — The request is contract-valid, but the operation, or a value the request names, is not applicable to this deployment. `details[].issue` is always `NOT_APPLICABLE`. For example, deployments and restarts are offered for `NODEJS` applications only, and a hosting product this deployment does not serve is answered here rather than with a `400`. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **503** — The service is temporarily unable to handle the request. Retry after a short delay. May include a `Retry-After` header hinting at when to retry. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # Update an application (https://developer.godaddy.com/en/docs/references/rest/hosting/update-app) --- title: Update an application description: 'Partial update via [JSON Patch (RFC 6902)](https://datatracker.' full: true --- Full description > Partial update via [JSON Patch (RFC 6902)](https://datatracker.ietf.org/doc/html/rfc6902). The request body is an array of operations applied in order and atomically. At least one operation must be present. Only the `replace` operation is supported, and only against the `/name` and `/rootPath` paths. Any other op or path returns `400 Bad Request`. - `/name` — human-readable display name. String, 1–200 characters. - `/rootPath` — subdirectory within the repository to treat as the application root. Write-only; not returned on the `Application` resource. Currently only supported for `NODEJS` applications. Additional product-specific paths will be documented when those paths are available. ## PATCH /apps/{appId} Update an application Partial update via [JSON Patch (RFC 6902)](https://datatracker.ietf.org/doc/html/rfc6902). The request body is an array of operations applied in order and atomically. At least one operation must be present. Only the `replace` operation is supported, and only against the `/name` and `/rootPath` paths. Any other op or path returns `400 Bad Request`. - `/name` — human-readable display name. String, 1–200 characters. - `/rootPath` — subdirectory within the repository to treat as the application root. Write-only; not returned on the `Application` resource. Currently only supported for `NODEJS` applications. Additional product-specific paths will be documented when those paths are available. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `appId` | string | yes | Application identifier in `{PRODUCT}-{id}` form. The prefix is the application type in upper case — an upper-case letter followed by any number of upper-case letters, digits, or underscores — then a hyphen, then the identifier. For `NODEJS`, the suffix is a 10-character nanoid. Example: `NODEJS-aBcDeFgHiJ`. | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `traceparent` | string | no | W3C Trace Context identifier for this request. Clients should send a `traceparent` on every request so the trace can be correlated across services. See https://www.w3.org/TR/trace-context/ for the format. | ### Request body (required) Content-Type: `application/json-patch+json` Schema: - schema reference: `#/x-ext/785f9fe` ### Responses **200** — Updated application. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/a87153c` **400** — The request body or parameters did not pass schema validation. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication credentials are missing or invalid. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — The caller is authenticated, but the request is not permitted: either the access token does not carry the scope this operation requires, or the operation is disabled for this account. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — The requested resource does not exist. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **422** — The request was well-formed but could not be processed due to a business rule violation. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Rate limit exceeded. A `429` response may come in one of two shapes: an empty body with `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` headers; or a JSON `Error` body with `Retry-After` and `RateLimit-*` headers. Clients should honour whichever headers are present and should not assume a JSON body is available on every `429`. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **503** — The service is temporarily unable to handle the request. Retry after a short delay. May include a `Retry-After` header hinting at when to retry. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # Update secrets (https://developer.godaddy.com/en/docs/references/rest/hosting/update-secrets) --- title: Update secrets description: 'Partial update via [JSON Patch (RFC 6902)](https://datatracker.' full: true --- Full description > Partial update via [JSON Patch (RFC 6902)](https://datatracker.ietf.org/doc/html/rfc6902). The request body is an array of operations applied in order and atomically. At least one operation must be present. The combined total number of operations must not exceed 50. Existing secrets not referenced in the request are left unchanged. The `variant` query parameter selects the environment (`PREVIEW` or `PUBLISH`). Defaults to `PREVIEW`. Supported operations are `add`, `replace`, and `remove`. Any other op returns `400 Bad Request`. Each path is `/{name}` — a JSON Pointer to the secret name, not an index into the `ScopedSecretSet` response. Encode `/` in a secret name as `~1` per RFC 6901. Secret names must start with a letter and contain only letters, digits, `/`, `_`, `+`, `=`, `.`, `@`, or `-`. Reserved environment variable names are rejected. System-managed and reserved secrets cannot be updated or deleted. For `add` and `replace`, `value` is the secret string (max 8 KB). `remove` does not take a value. A request that would leave the application with more than 50 secrets returns `400 Bad Request`. The response is secret metadata after the update. Values are never included. ## PATCH /apps/{appId}/secrets Update secrets Partial update via [JSON Patch (RFC 6902)](https://datatracker.ietf.org/doc/html/rfc6902). The request body is an array of operations applied in order and atomically. At least one operation must be present. The combined total number of operations must not exceed 50. Existing secrets not referenced in the request are left unchanged. The `variant` query parameter selects the environment (`PREVIEW` or `PUBLISH`). Defaults to `PREVIEW`. Supported operations are `add`, `replace`, and `remove`. Any other op returns `400 Bad Request`. Each path is `/{name}` — a JSON Pointer to the secret name, not an index into the `ScopedSecretSet` response. Encode `/` in a secret name as `~1` per RFC 6901. Secret names must start with a letter and contain only letters, digits, `/`, `_`, `+`, `=`, `.`, `@`, or `-`. Reserved environment variable names are rejected. System-managed and reserved secrets cannot be updated or deleted. For `add` and `replace`, `value` is the secret string (max 8 KB). `remove` does not take a value. A request that would leave the application with more than 50 secrets returns `400 Bad Request`. The response is secret metadata after the update. Values are never included. ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `variant` | unknown | no | The environment variant to target. Defaults to `PREVIEW`. | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `Idempotency-Key` | string | no | Client-generated UUID that makes a request safe to retry. Supplying the same key on a retry with an identical request body returns the original response without triggering a second operation. Retrying with the same key while the first request is still in flight returns `409 Conflict`. Reusing a key with a different request body returns `422 Unprocessable Entity` with `details[].issue` `IDEMPOTENCY_KEY_MISMATCH`. Keys are retained for 24 hours after the operation completes, after which the key may be reused. | ### Request body (required) Content-Type: `application/json-patch+json` Schema: - schema reference: `#/x-ext/785f9fe` ### Responses **200** — Secret metadata after the update. Values are never included. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/3c029b5` **400** — The request body or parameters did not pass schema validation. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication credentials are missing or invalid. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — The caller is authenticated, but the request is not permitted: either the access token does not carry the scope this operation requires, or the operation is disabled for this account. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — The requested resource does not exist. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **409** — The request conflicts with the current state of the resource. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **422** — The request was well-formed but could not be processed due to a business rule violation. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Rate limit exceeded. A `429` response may come in one of two shapes: an empty body with `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` headers; or a JSON `Error` body with `Retry-After` and `RateLimit-*` headers. Clients should honour whichever headers are present and should not assume a JSON body is available on every `429`. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **501** — The request is contract-valid, but the operation, or a value the request names, is not applicable to this deployment. `details[].issue` is always `NOT_APPLICABLE`. For example, deployments and restarts are offered for `NODEJS` applications only, and a hosting product this deployment does not serve is answered here rather than with a `400`. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **503** — The service is temporarily unable to handle the request. Retry after a short delay. May include a `Retry-After` header hinting at when to retry. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # Orders GraphQL (https://developer.godaddy.com/en/docs/references/rest/orders) --- title: Orders GraphQL description: Query and mutate the commerce order subgraph. full: true --- Commerce order GraphQL over HTTP. Use `commerce.order:read` to query; mutations require one of `commerce.order:create`, `:update`, `:cancel`, or `:complete`. See [Commerce API Scopes](https://developer.godaddy.com/docs/references/rest/commerce-scopes). **Endpoint:** `POST /v1/commerce/order-subgraph` Select the store with a required `x-store-id` header — there is no `{storeId}` path segment on this endpoint. Mutations that take an input object also include a required `context.storeId`; `id`-only mutations (e.g. `cancelOrder`) rely on the header alone. Order and line-item IDs are opaque global IDs shaped like `Order_` and `LineItem_` (e.g. `Order_2N8x…`) — not numeric or base64-encoded. Pass the full value verbatim wherever an `id` or `orderId` argument appears. Sidebar is grouped by **action/resource**. Expand a resource, then **Query** (`commerce.order:read`, 6 fields) or **Mutation** (15 fields). ## Example query query Requires `commerce.order:read`. See [`orderById`](https://developer.godaddy.com/docs/references/rest/orders/order/queries/orderById) for the full schema. ```graphql query GetOrder($id: ID!) { orderById(id: $id) { id number statuses { status } } } ``` ```bash curl -X POST "https://api.godaddy.com/v1/commerce/order-subgraph" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "Content-Type: application/json" \ -H "x-store-id: $STORE_ID" \ -d '{ "query": "query GetOrder($id: ID!) { orderById(id: $id) { id number statuses { status } } }", "variables": { "id": "ORDER_ID" } }' ``` ## Example mutation mutation Requires the scope matching the operation (e.g. `commerce.order:cancel`). See [`addOrder`](https://developer.godaddy.com/docs/references/rest/orders/order/mutations/addOrder) for the full schema. ```graphql mutation CancelOrder($id: ID!, $force: Boolean) { cancelOrder(id: $id, force: $force) { id statuses { status } } } ``` ## Error handling This is a GraphQL endpoint, so **most failures still return HTTP 200**. Resolver and authorization errors are reported inside the `errors` array — inspect `errors[].extensions.code` rather than keying off the HTTP status. Only malformed GraphQL documents fail at the transport layer with HTTP 400. | `extensions.code` | HTTP | When | | --------------------------- | ---- | ----------------------------------------------------------------------------------------------------------------- | | `UNAUTHENTICATED` | 200 | A store-scoped operation was called without a valid `x-store-id` header. | | `INTERNAL_SERVER_ERROR` | 200 | The `x-store-id` header is present but is invalid or not a store you can access (a masked authorization failure). | | `GRAPHQL_VALIDATION_FAILED` | 400 | The query references an unknown field or is otherwise not valid against the schema. | ```json { "data": null, "errors": [ { "message": "Unauthorized", "extensions": { "code": "UNAUTHENTICATED" } } ] } ``` *** ## HTTP reference OpenAPI contract for the subgraph POST (headers, auth, response envelope): ## POST /v1/commerce/order-subgraph Order GraphQL endpoint Proxies GraphQL to the order subgraph. Use the `query` field for the GraphQL document and optional `variables` / `operationName`. ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `x-store-id` | string | yes | ID of the store the operation targets — send it on every request. Required for all order queries and mutations; omitting it returns HTTP 200 with a GraphQL error whose `extensions.code` is `UNAUTHENTICATED`. (Schema-level metadata requests such as `__typename` and introspection are the only operations that resolve without it.) | ### Request body (required) Content-Type: `application/json` ```json { "query": "query GetOrder($id: ID!) { orderById(id: $id) { id number statuses { status } } }", "variables": { "id": "ORDER_ID" } } ``` Schema: - object - `query` (required): string - `variables`: object - `operationName`: string ### Responses **200** — GraphQL response Content-Type: `application/json` Schema: - object - `data`: object - `errors`: array - items: **400** — Invalid request **401** — Unauthorized **403** — Forbidden **500** — Internal server error **Security:** requires `PAT`; scopes `commerce.order:read`, `commerce.order:create`, `commerce.order:update`, `commerce.order:cancel`, `commerce.order:complete`, `commerce.order:archive`. # List domain metrics (https://developer.godaddy.com/en/docs/references/rest/parking/get-metrics-by-domain) --- title: List domain metrics full: true --- ## GET /v1/customers/{customerId}/parking/metricsByDomain List domain metrics ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `customerId` | string | yes | An identifier for a customer. A special alias MY is supported when accessing the authenticated customer's own data | ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `startDate` | string | yes | Start of range indicating what time-frame should be returned, inclusive. ISO 8601 date YYYY-MM-DD | | `endDate` | string | yes | End of range indicating what time-frame should be returned, inclusive. ISO 8601 date YYYY-MM-DD | | `domains` | string | no | An array of domains to filter the results. If this filter is not provided, all domains will be returned | | `domainLike` | string | no | represent search keyword filtering domains. If not null, `domains` will be ignored | | `portfolioId` | string | no | Unique identifier for the portfolio to filter the results. If not provided, all domains within all porfolios will be returned | | `limit` | integer | no | Maximum number of items to return | | `offset` | integer | no | Number of results to skip for pagination | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | string | no | A unique identifier for the request | ### Responses **200** — Request was successful Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/MetricByDomainList` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **422** — Required parameters must be specified in correct format Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` # List parking metrics (https://developer.godaddy.com/en/docs/references/rest/parking/get-metrics) --- title: List parking metrics full: true --- ## GET /v1/customers/{customerId}/parking/metrics List parking metrics ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `customerId` | string | yes | An identifier for a customer. A special alias MY is supported when accessing the authenticated customer's own data | ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `periodStartPtz` | string | no | Start of range indicating what time-frame should be returned, ***inclusive***. ISO 8601 date `YYYY-MM-DD` in PT. Default value is the day before current date | | `periodEndPtz` | string | no | End of range indicating what time-frame should be returned, ***inclusive***. ISO 8601 date `YYYY-MM-DD` in PT. Default value is the day before current date | | `limit` | integer | no | Maximum number of items to return | | `offset` | integer | no | Number of results to skip for pagination | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | string | no | A unique identifier for the request | ### Responses **200** — Request was successful Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/MetricList` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **422** — Required parameters must be specified in correct format Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` # Set subaccount's password (https://developer.godaddy.com/en/docs/references/rest/shoppers/change-password) --- title: Set subaccount's password description: >- Notes:
  1. Password set is only supported by API Resellers setting subaccount passwords. full: true --- Full description Notes:Password set is only supported by API Resellers setting subaccount passwords. ## PUT /v1/shoppers/{shopperId}/factors/password Set subaccount's password Notes:
    1. Password set is only supported by API Resellers setting subaccount passwords.
    ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `shopperId` | string | yes | Shopper whose password will be set | ### Request body (required) The value to set the subaccount's password to Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Secret` ### Responses **200** — Request was successful Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ShopperId` **400** — Request was not successful Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/PasswordError` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` # Create a Subaccount owned by the authenticated Reseller (https://developer.godaddy.com/en/docs/references/rest/shoppers/create-subaccount) --- title: Create a Subaccount owned by the authenticated Reseller full: true --- ## POST /v1/shoppers/subaccount Create a Subaccount owned by the authenticated Reseller ### Request body (required) The subaccount to create Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/SubaccountCreate` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/SubaccountCreate` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/SubaccountCreate` ### Responses **200** — Request was successful Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ShopperId` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/ShopperId` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/ShopperId` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/ShopperId` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/ShopperId` **400** — Request was malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **422** — `subaccount` does not fulfill the schema Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` # Request the deletion of a shopper profile (https://developer.godaddy.com/en/docs/references/rest/shoppers/delete) --- title: Request the deletion of a shopper profile description: >- Notes:
    1. Shopper deletion is not supported in production — contact GoDaddy support for account removal. full: true --- Full description Notes:Shopper deletion is not supported in production — contact GoDaddy support for account removal. ## DELETE /v1/shoppers/{shopperId} Request the deletion of a shopper profile Notes:
      1. Shopper deletion is not supported in production — contact GoDaddy support for account removal.
      ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `shopperId` | string | yes | The ID of the shopper to delete. Must agree with the shopper id on the token or header, if present | ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `auditClientIp` | string | yes | The client IP of the user who originated the request leading to this call. | ### Responses **204** — Request was successful **400** — Request was malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **404** — Resource not found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **409** — Active and locked shoppers cannot be deleted Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **422** — Shopper ID is not supplied or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` # Get details for the specified Shopper (https://developer.godaddy.com/en/docs/references/rest/shoppers/get-status) --- title: Get details for the specified Shopper full: true --- ## GET /v1/shoppers/{shopperId}/status Get details for the specified Shopper ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `shopperId` | string | yes | The ID of the shopper to retrieve. Must agree with the shopper id on the token or header, if present | ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `auditClientIp` | string | yes | The client IP of the user who originated the request leading to this call. | ### Responses **200** — Request was successful Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ShopperStatus` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/ShopperStatus` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/ShopperStatus` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/ShopperStatus` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/ShopperStatus` **400** — Request was malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **404** — Resource not found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **422** — Shopper ID is not supplied or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` # Get details for the specified Shopper (https://developer.godaddy.com/en/docs/references/rest/shoppers/get) --- title: Get details for the specified Shopper full: true --- ## GET /v1/shoppers/{shopperId} Get details for the specified Shopper ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `shopperId` | string | yes | Shopper whose details are to be retrieved | ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `includes` | array | no | Additional properties to be included in the response shopper object | ### Responses **200** — Request was successful Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Shopper` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Shopper` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Shopper` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Shopper` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Shopper` **400** — Request was malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **404** — Resource not found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` # Update details for the specified Shopper (https://developer.godaddy.com/en/docs/references/rest/shoppers/update) --- title: Update details for the specified Shopper full: true --- ## POST /v1/shoppers/{shopperId} Update details for the specified Shopper ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `shopperId` | string | yes | The ID of the Shopper to update | ### Request body (required) The Shopper details to update Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ShopperUpdate` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/ShopperUpdate` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/ShopperUpdate` ### Responses **200** — Request was successful Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ShopperId` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/ShopperId` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/ShopperId` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/ShopperId` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/ShopperId` **400** — Request was malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **404** — Resource not found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **422** — `Shopper` does not fulfill the schema Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` # Complete a checkout session (https://developer.godaddy.com/en/docs/references/rest/shopping/complete-checkout) --- title: Complete a checkout session description: Complete a ready checkout session and create its order. full: true --- Full description > Complete a ready checkout session and create its order. `payment` is required. The successful response includes an order ID and receipt URL; use `GET /orders/{id}` to retrieve full order details. If the checkout response includes `required_agreements`, include each required key in `consent.agreement_types` with its acceptance timestamp. Missing or incomplete consent returns a `400` validation error. ## POST /checkout-sessions/{id}/complete Complete a checkout session Complete a ready checkout session and create its order. `payment` is required. The successful response includes an order ID and receipt URL; use `GET /orders/{id}` to retrieve full order details. If the checkout response includes `required_agreements`, include each required key in `consent.agreement_types` with its acceptance timestamp. Missing or incomplete consent returns a `400` validation error. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `id` | string | yes | The unique identifier of the checkout session. | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `Request-Id` | string | yes | For tracing the request across network layers and components. | | `Idempotency-Key` | string | yes | Ensures duplicate operations don't happen during retries. | ### Request body (required) Content-Type: `application/json` ```json { "payment": { "instruments": [ { "id": "profile_visa", "handler_id": "com.godaddy.payments", "type": "card", "selected": true } ] }, "consent": { "agreement_types": [ "api_services_purchase_agreement" ], "agreed_at": "2026-09-14T20:00:00Z" } } ``` Schema: - schema reference: `#/components/schemas/checkout_complete_request` ### Responses **200** — Completed checkout session with order confirmation or an error envelope. Content-Type: `application/json` ```json { "ucp": { "version": "2026-04-08", "capabilities": { "dev.ucp.shopping.checkout": [ { "version": "2026-04-08" } ], "com.godaddy.shopping.input": [ { "version": "2026-04-08" } ], "com.godaddy.shopping.catalog_offer": [ { "version": "2026-04-08" } ] }, "payment_handlers": { "com.godaddy.payments": [ { "id": "com.godaddy.payments", "version": "2026-04-08" } ] } }, "id": "d9cf79e3-b39b-4e58-8f30-ddfe1619e969", "line_items": [ { "id": "li_1", "item": { "id": "hosting-deluxeapi:1mo", "title": "Web Hosting Deluxe — 1 Month", "price": 1099 }, "quantity": 1, "totals": [ { "type": "subtotal", "amount": 1099 }, { "type": "total", "amount": 1099 } ] } ], "status": "completed", "currency": "USD", "totals": [ { "type": "subtotal", "amount": 1099 }, { "type": "total", "amount": 1099 } ], "links": [ { "type": "privacy_policy", "url": "https://www.godaddy.com/legal/agreements/privacy-policy" }, { "type": "terms_of_service", "url": "https://www.godaddy.com/legal/agreements/terms-of-service" } ], "order": { "id": "2211390786", "permalink_url": "https://account.godaddy.com/receipts/view/2211390786" } } ``` Schema: - oneOf(unknown | unknown) **400** — Request validation or caller-correctable business error, including missing agreement consent. Content-Type: `application/json` ```json { "ucp": { "version": "2026-04-08", "status": "error" }, "messages": [ { "type": "error", "code": "validation_error", "path": "consent.agreement_types", "content": "Missing required agreement acceptance: [api_services_purchase_agreement]", "severity": "recoverable" } ] } ``` Schema: - schema reference: `#/components/schemas/error_response` **401** — Missing or invalid credentials. **403** — Authenticated credential lacks the required Shopping scope. **404** — Resource does not exist. Content-Type: `application/json` ```json { "ucp": { "version": "2026-04-08", "status": "error" }, "messages": [ { "type": "error", "code": "product_not_found", "content": "Product not found: not-a-real-product", "severity": "unrecoverable" } ] } ``` Schema: - schema reference: `#/components/schemas/error_response` **422** — Request is syntactically valid but cannot be processed in its current state. Content-Type: `application/json` ```json { "ucp": { "version": "2026-04-08", "status": "error" }, "messages": [ { "type": "error", "code": "unsupported_currency", "content": "Currency not supported: ZZZ", "severity": "recoverable" } ] } ``` Schema: - schema reference: `#/components/schemas/error_response` **429** — Too many requests. **Security:** requires `bearerAuth`. # Create a checkout session (https://developer.godaddy.com/en/docs/references/rest/shopping/create-checkout) --- title: Create a checkout session description: Create a checkout session for the authenticated customer. full: true --- Full description > Create a checkout session for the authenticated customer. Provide at least one selected product in `line_items[]`. Buyer contact details, context, and payment selection are optional. The response is `incomplete` until it has purchasable line items and a selected eligible saved payment instrument. For POS and hardware products, use `input` with a `commerce_location` type and the required business and store IDs. ## POST /checkout-sessions Create a checkout session Create a checkout session for the authenticated customer. Provide at least one selected product in `line_items[]`. Buyer contact details, context, and payment selection are optional. The response is `incomplete` until it has purchasable line items and a selected eligible saved payment instrument. For POS and hardware products, use `input` with a `commerce_location` type and the required business and store IDs. ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `Request-Id` | string | yes | For tracing the request across network layers and components. | | `Idempotency-Key` | string | yes | Ensures duplicate operations don't happen during retries. | ### Request body (required) Content-Type: `application/json` ```json { "line_items": [ { "item": { "id": "hosting-deluxeapi:1mo" }, "quantity": 1 } ] } ``` Schema: - schema reference: `#/components/schemas/checkout_writable_request` ### Responses **201** — Checkout session created or an error envelope. Content-Type: `application/json` ```json { "ucp": { "version": "2026-04-08", "capabilities": { "dev.ucp.shopping.checkout": [ { "version": "2026-04-08" } ], "com.godaddy.shopping.input": [ { "version": "2026-04-08" } ], "com.godaddy.shopping.catalog_offer": [ { "version": "2026-04-08" } ] }, "payment_handlers": { "com.godaddy.payments": [ { "id": "com.godaddy.payments", "version": "2026-04-08" } ] } }, "id": "d9cf79e3-b39b-4e58-8f30-ddfe1619e969", "line_items": [ { "id": "li_1", "item": { "id": "hosting-deluxeapi:1mo", "title": "Web Hosting Deluxe — 1 Month", "price": 1099 }, "quantity": 1, "totals": [ { "type": "subtotal", "amount": 1099 }, { "type": "total", "amount": 1099 } ] } ], "status": "incomplete", "currency": "USD", "totals": [ { "type": "subtotal", "amount": 1099 }, { "type": "total", "amount": 1099 } ], "links": [ { "type": "privacy_policy", "url": "https://www.godaddy.com/legal/agreements/privacy-policy" }, { "type": "terms_of_service", "url": "https://www.godaddy.com/legal/agreements/terms-of-service" } ] } ``` Schema: - oneOf(unknown | unknown) **400** — Request validation or caller-correctable business error. Content-Type: `application/json` ```json { "ucp": { "version": "2026-04-08", "status": "error" }, "messages": [ { "type": "error", "code": "invalid_request", "content": "Lookup request must include at least one id.", "severity": "recoverable" } ] } ``` Schema: - schema reference: `#/components/schemas/error_response` **401** — Missing or invalid credentials. **403** — Authenticated credential lacks the required Shopping scope. **404** — Resource does not exist. Content-Type: `application/json` ```json { "ucp": { "version": "2026-04-08", "status": "error" }, "messages": [ { "type": "error", "code": "product_not_found", "content": "Product not found: not-a-real-product", "severity": "unrecoverable" } ] } ``` Schema: - schema reference: `#/components/schemas/error_response` **422** — Request is syntactically valid but cannot be processed in its current state. Content-Type: `application/json` ```json { "ucp": { "version": "2026-04-08", "status": "error" }, "messages": [ { "type": "error", "code": "unsupported_currency", "content": "Currency not supported: ZZZ", "severity": "recoverable" } ] } ``` Schema: - schema reference: `#/components/schemas/error_response` **429** — Too many requests. **Security:** requires `bearerAuth`. # Get a checkout session (https://developer.godaddy.com/en/docs/references/rest/shopping/get-checkout) --- title: Get a checkout session description: >- Retrieve the current checkout session state, including line items, totals, selected payment instruments, messages, and required agreements. full: true --- Full description > Retrieve the current checkout session state, including line items, totals, selected payment instruments, messages, and required agreements. ## GET /checkout-sessions/{id} Get a checkout session Retrieve the current checkout session state, including line items, totals, selected payment instruments, messages, and required agreements. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `id` | string | yes | The unique identifier of the checkout session. | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `Request-Id` | string | yes | For tracing the request across network layers and components. | ### Responses **200** — Checkout session or an error envelope. Content-Type: `application/json` ```json { "ucp": { "version": "2026-04-08", "capabilities": { "dev.ucp.shopping.checkout": [ { "version": "2026-04-08" } ], "com.godaddy.shopping.input": [ { "version": "2026-04-08" } ], "com.godaddy.shopping.catalog_offer": [ { "version": "2026-04-08" } ] }, "payment_handlers": { "com.godaddy.payments": [ { "id": "com.godaddy.payments", "version": "2026-04-08" } ] } }, "id": "d9cf79e3-b39b-4e58-8f30-ddfe1619e969", "line_items": [ { "id": "li_1", "item": { "id": "hosting-deluxeapi:1mo", "title": "Web Hosting Deluxe — 1 Month", "price": 1099 }, "quantity": 1, "totals": [ { "type": "subtotal", "amount": 1099 }, { "type": "total", "amount": 1099 } ] } ], "status": "ready_for_complete", "currency": "USD", "totals": [ { "type": "subtotal", "amount": 1099 }, { "type": "total", "amount": 1099 } ], "links": [ { "type": "privacy_policy", "url": "https://www.godaddy.com/legal/agreements/privacy-policy" }, { "type": "terms_of_service", "url": "https://www.godaddy.com/legal/agreements/terms-of-service" } ], "payment": { "instruments": [ { "id": "profile_visa", "handler_id": "com.godaddy.payments", "type": "card", "selected": true, "display": { "brand": "visa", "last_digits": "4242" } }, { "id": "profile_mastercard", "handler_id": "com.godaddy.payments", "type": "card", "selected": false, "display": { "brand": "mastercard", "last_digits": "4444" } } ] } } ``` Schema: - oneOf(unknown | unknown) **400** — Request validation or caller-correctable business error. Content-Type: `application/json` ```json { "ucp": { "version": "2026-04-08", "status": "error" }, "messages": [ { "type": "error", "code": "invalid_request", "content": "Lookup request must include at least one id.", "severity": "recoverable" } ] } ``` Schema: - schema reference: `#/components/schemas/error_response` **401** — Missing or invalid credentials. **403** — Authenticated credential lacks the required Shopping scope. **404** — Resource does not exist. Content-Type: `application/json` ```json { "ucp": { "version": "2026-04-08", "status": "error" }, "messages": [ { "type": "error", "code": "product_not_found", "content": "Product not found: not-a-real-product", "severity": "unrecoverable" } ] } ``` Schema: - schema reference: `#/components/schemas/error_response` **422** — Request is syntactically valid but cannot be processed in its current state. Content-Type: `application/json` ```json { "ucp": { "version": "2026-04-08", "status": "error" }, "messages": [ { "type": "error", "code": "unsupported_currency", "content": "Currency not supported: ZZZ", "severity": "recoverable" } ] } ``` Schema: - schema reference: `#/components/schemas/error_response` **429** — Too many requests. **Security:** requires `bearerAuth`. # Get order (https://developer.godaddy.com/en/docs/references/rest/shopping/get-order) --- title: Get order description: Retrieve an order created by a completed checkout session. full: true --- Full description > Retrieve an order created by a completed checkout session. The response includes line items, totals, fulfillment details, and a receipt URL. ## GET /orders/{id} Get order Retrieve an order created by a completed checkout session. The response includes line items, totals, fulfillment details, and a receipt URL. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `id` | string | yes | Unique order identifier. | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `Request-Id` | string | yes | For tracing the request across network layers and components. | ### Responses **200** — Order detail or an error envelope. Content-Type: `application/json` ```json { "ucp": { "version": "2026-04-08", "capabilities": { "dev.ucp.shopping.order": [ { "version": "2026-04-08" } ] } }, "id": "12345", "checkout_id": "d9cf79e3-b39b-4e58-8f30-ddfe1619e969", "permalink_url": "https://account.godaddy.com/receipts/view/12345", "line_items": [ { "id": "oli_1", "item": { "id": "hosting-deluxeapi:1mo", "title": "Web Hosting Deluxe — 1 Month", "price": 1099 }, "quantity": { "total": 1, "fulfilled": 1 }, "totals": [ { "type": "subtotal", "amount": 1099 }, { "type": "total", "amount": 1099 } ], "status": "fulfilled" } ], "fulfillment": { "expectations": [ { "id": "exp_1", "line_items": [ { "id": "oli_1", "quantity": 1 } ], "method_type": "digital", "description": "Digital product fulfillment.", "fulfillable_on": "now" } ] }, "currency": "USD", "totals": [ { "type": "subtotal", "amount": 1099 }, { "type": "total", "amount": 1099 } ] } ``` Schema: - oneOf(unknown | unknown) **400** — Request validation or caller-correctable business error. Content-Type: `application/json` ```json { "ucp": { "version": "2026-04-08", "status": "error" }, "messages": [ { "type": "error", "code": "invalid_request", "content": "Lookup request must include at least one id.", "severity": "recoverable" } ] } ``` Schema: - schema reference: `#/components/schemas/error_response` **401** — Missing or invalid credentials. **403** — Authenticated credential lacks the required Shopping scope. **404** — Resource does not exist. Content-Type: `application/json` ```json { "ucp": { "version": "2026-04-08", "status": "error" }, "messages": [ { "type": "error", "code": "product_not_found", "content": "Product not found: not-a-real-product", "severity": "unrecoverable" } ] } ``` Schema: - schema reference: `#/components/schemas/error_response` **422** — Request is syntactically valid but cannot be processed in its current state. Content-Type: `application/json` ```json { "ucp": { "version": "2026-04-08", "status": "error" }, "messages": [ { "type": "error", "code": "unsupported_currency", "content": "Currency not supported: ZZZ", "severity": "recoverable" } ] } ``` Schema: - schema reference: `#/components/schemas/error_response` **429** — Too many requests. **Security:** requires `bearerAuth`. # Get product details (https://developer.godaddy.com/en/docs/references/rest/shopping/get-product) --- title: Get product details description: Retrieve details for one product by ID. full: true --- Full description > Retrieve details for one product by ID. The current catalog does not support option selection or preference-based narrowing; send only `id`. Use catalog search to discover products. ## POST /catalog/product Get product details Retrieve details for one product by ID. The current catalog does not support option selection or preference-based narrowing; send only `id`. Use catalog search to discover products. ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `Request-Id` | string | yes | For tracing the request across network layers and components. | ### Request body (required) Content-Type: `application/json` ```json { "id": "hosting-deluxeapi" } ``` Schema: - schema reference: `#/components/schemas/get_product_request` ### Responses **200** — Product detail or an error envelope. Content-Type: `application/json` ```json { "ucp": { "version": "2026-04-08", "capabilities": { "dev.ucp.shopping.catalog.lookup": [ { "version": "2026-04-08" } ], "com.godaddy.shopping.input": [ { "version": "2026-04-08" } ], "com.godaddy.shopping.catalog_action": [ { "version": "2026-04-08" } ], "com.godaddy.shopping.catalog_offer": [ { "version": "2026-04-08" } ] } }, "product": { "id": "hosting-deluxeapi", "title": "Web Hosting Deluxe — Monthly", "description": { "plain": "Web Hosting on the Deluxe plan, which also includes Node.js Hosting for deploying your app. Billed monthly with automatic renewal." }, "categories": [ { "value": "webHosting" } ], "price_range": { "min": { "amount": 1099, "currency": "USD" }, "max": { "amount": 1099, "currency": "USD" } }, "variants": [ { "id": "hosting-deluxeapi:1mo", "title": "Web Hosting Deluxe — 1 Month", "description": { "plain": "Web Hosting Deluxe, 1-month term." }, "price": { "amount": 1099, "currency": "USD" }, "list_price": { "amount": 1099, "currency": "USD" }, "availability": { "available": true }, "options": [ { "name": "Term", "id": "1mo", "label": "1 Month" } ] } ] } } ``` Schema: - oneOf(unknown | unknown) **400** — Request validation or caller-correctable business error. Content-Type: `application/json` ```json { "ucp": { "version": "2026-04-08", "status": "error" }, "messages": [ { "type": "error", "code": "invalid_request", "content": "Lookup request must include at least one id.", "severity": "recoverable" } ] } ``` Schema: - schema reference: `#/components/schemas/error_response` **401** — Missing or invalid credentials. **403** — Authenticated credential lacks the required Shopping scope. **404** — Resource does not exist. Content-Type: `application/json` ```json { "ucp": { "version": "2026-04-08", "status": "error" }, "messages": [ { "type": "error", "code": "product_not_found", "content": "Product not found: not-a-real-product", "severity": "unrecoverable" } ] } ``` Schema: - schema reference: `#/components/schemas/error_response` **422** — Request is syntactically valid but cannot be processed in its current state. Content-Type: `application/json` ```json { "ucp": { "version": "2026-04-08", "status": "error" }, "messages": [ { "type": "error", "code": "unsupported_currency", "content": "Currency not supported: ZZZ", "severity": "recoverable" } ] } ``` Schema: - schema reference: `#/components/schemas/error_response` **429** — Too many requests. **Security:** requires `bearerAuth`. # Look up products by ID (https://developer.godaddy.com/en/docs/references/rest/shopping/lookup-catalog) --- title: Look up products by ID description: Retrieve products or variants by known ID. full: true --- Full description > Retrieve products or variants by known ID. Each returned variant includes `inputs[]` that identifies the requested ID it matched. Unresolved IDs are returned as informational messages instead of a not-found response. Use catalog search for product discovery. ## POST /catalog/lookup Look up products by ID Retrieve products or variants by known ID. Each returned variant includes `inputs[]` that identifies the requested ID it matched. Unresolved IDs are returned as informational messages instead of a not-found response. Use catalog search for product discovery. ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `Request-Id` | string | yes | For tracing the request across network layers and components. | ### Request body (required) Content-Type: `application/json` ```json { "ids": [ "hosting-deluxeapi:1mo" ], "context": { "currency": "USD" } } ``` Schema: - schema reference: `#/components/schemas/lookup_request` ### Responses **200** — Lookup results, informational unresolved-ID messages, or an error envelope. Content-Type: `application/json` ```json { "ucp": { "version": "2026-04-08", "capabilities": { "dev.ucp.shopping.catalog.lookup": [ { "version": "2026-04-08" } ], "com.godaddy.shopping.input": [ { "version": "2026-04-08" } ], "com.godaddy.shopping.catalog_action": [ { "version": "2026-04-08" } ], "com.godaddy.shopping.catalog_offer": [ { "version": "2026-04-08" } ] } }, "products": [ { "id": "hosting-deluxeapi", "title": "Web Hosting Deluxe — Monthly", "description": { "plain": "Web Hosting on the Deluxe plan, which also includes Node.js Hosting for deploying your app. Billed monthly with automatic renewal." }, "categories": [ { "value": "webHosting" } ], "price_range": { "min": { "amount": 1099, "currency": "USD" }, "max": { "amount": 1099, "currency": "USD" } }, "variants": [ { "id": "hosting-deluxeapi:1mo", "title": "Web Hosting Deluxe — 1 Month", "description": { "plain": "Web Hosting Deluxe, 1-month term." }, "price": { "amount": 1099, "currency": "USD" }, "list_price": { "amount": 1099, "currency": "USD" }, "availability": { "available": true }, "options": [ { "name": "Term", "id": "1mo", "label": "1 Month" } ], "inputs": [ { "id": "hosting-deluxeapi:1mo", "match": "exact" } ] } ] } ] } ``` Schema: - oneOf(unknown | unknown) **400** — Request validation or caller-correctable business error. Content-Type: `application/json` ```json { "ucp": { "version": "2026-04-08", "status": "error" }, "messages": [ { "type": "error", "code": "invalid_request", "content": "Lookup request must include at least one id.", "severity": "recoverable" } ] } ``` Schema: - schema reference: `#/components/schemas/error_response` **401** — Missing or invalid credentials. **403** — Authenticated credential lacks the required Shopping scope. **404** — Resource does not exist. Content-Type: `application/json` ```json { "ucp": { "version": "2026-04-08", "status": "error" }, "messages": [ { "type": "error", "code": "product_not_found", "content": "Product not found: not-a-real-product", "severity": "unrecoverable" } ] } ``` Schema: - schema reference: `#/components/schemas/error_response` **422** — Request is syntactically valid but cannot be processed in its current state. Content-Type: `application/json` ```json { "ucp": { "version": "2026-04-08", "status": "error" }, "messages": [ { "type": "error", "code": "unsupported_currency", "content": "Currency not supported: ZZZ", "severity": "recoverable" } ] } ``` Schema: - schema reference: `#/components/schemas/error_response` **429** — Too many requests. **Security:** requires `bearerAuth`. # Search the catalog (https://developer.godaddy.com/en/docs/references/rest/shopping/search-catalog) --- title: Search the catalog description: Search available catalog products by free-text query or filters. full: true --- Full description > Search available catalog products by free-text query or filters. The request body is optional; an empty request returns the available catalog. Results use cursor pagination. ## POST /catalog/search Search the catalog Search available catalog products by free-text query or filters. The request body is optional; an empty request returns the available catalog. Results use cursor pagination. ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `Request-Id` | string | yes | For tracing the request across network layers and components. | ### Request body Content-Type: `application/json` ```json { "context": { "address_country": "US", "currency": "USD", "language": "en" }, "pagination": { "limit": 20 } } ``` Schema: - schema reference: `#/components/schemas/search_request` ### Responses **200** — Search results or an error envelope. Content-Type: `application/json` ```json { "ucp": { "version": "2026-04-08", "capabilities": { "dev.ucp.shopping.catalog.search": [ { "version": "2026-04-08" } ], "com.godaddy.shopping.input": [ { "version": "2026-04-08" } ], "com.godaddy.shopping.catalog_action": [ { "version": "2026-04-08" } ], "com.godaddy.shopping.catalog_offer": [ { "version": "2026-04-08" } ] } }, "products": [ { "id": "hosting-economyapi", "title": "Web Hosting Economy — Monthly", "description": { "plain": "Web Hosting on the Economy plan, which also includes Node.js Hosting for deploying your app. Billed monthly with automatic renewal." }, "categories": [ { "value": "webHosting" } ], "price_range": { "min": { "amount": 799, "currency": "USD" }, "max": { "amount": 799, "currency": "USD" } }, "variants": [ { "id": "hosting-economyapi:1mo", "title": "Web Hosting Economy — 1 Month", "description": { "plain": "Web Hosting Economy, 1-month term." }, "price": { "amount": 799, "currency": "USD" }, "list_price": { "amount": 799, "currency": "USD" }, "availability": { "available": true }, "options": [ { "name": "Term", "id": "1mo", "label": "1 Month" } ] } ] }, { "id": "hosting-deluxeapi", "title": "Web Hosting Deluxe — Monthly", "description": { "plain": "Web Hosting on the Deluxe plan, which also includes Node.js Hosting for deploying your app. Billed monthly with automatic renewal." }, "categories": [ { "value": "webHosting" } ], "price_range": { "min": { "amount": 1099, "currency": "USD" }, "max": { "amount": 1099, "currency": "USD" } }, "variants": [ { "id": "hosting-deluxeapi:1mo", "title": "Web Hosting Deluxe — 1 Month", "description": { "plain": "Web Hosting Deluxe, 1-month term." }, "price": { "amount": 1099, "currency": "USD" }, "list_price": { "amount": 1099, "currency": "USD" }, "availability": { "available": true }, "options": [ { "name": "Term", "id": "1mo", "label": "1 Month" } ] } ] }, { "id": "hosting-ultimateapi", "title": "Web Hosting Ultimate — Monthly", "description": { "plain": "Web Hosting on the Ultimate plan, which also includes Node.js Hosting for deploying your app. Billed monthly with automatic renewal." }, "categories": [ { "value": "webHosting" } ], "price_range": { "min": { "amount": 1599, "currency": "USD" }, "max": { "amount": 1599, "currency": "USD" } }, "variants": [ { "id": "hosting-ultimateapi:1mo", "title": "Web Hosting Ultimate — 1 Month", "description": { "plain": "Web Hosting Ultimate, 1-month term." }, "price": { "amount": 1599, "currency": "USD" }, "list_price": { "amount": 1599, "currency": "USD" }, "availability": { "available": true }, "options": [ { "name": "Term", "id": "1mo", "label": "1 Month" } ] } ] } ], "pagination": { "has_next_page": false, "total_count": 3 } } ``` Schema: - oneOf(unknown | unknown) **400** — Request validation or caller-correctable business error. Content-Type: `application/json` ```json { "ucp": { "version": "2026-04-08", "status": "error" }, "messages": [ { "type": "error", "code": "invalid_request", "content": "Lookup request must include at least one id.", "severity": "recoverable" } ] } ``` Schema: - schema reference: `#/components/schemas/error_response` **401** — Missing or invalid credentials. **403** — Authenticated credential lacks the required Shopping scope. **404** — Resource does not exist. Content-Type: `application/json` ```json { "ucp": { "version": "2026-04-08", "status": "error" }, "messages": [ { "type": "error", "code": "product_not_found", "content": "Product not found: not-a-real-product", "severity": "unrecoverable" } ] } ``` Schema: - schema reference: `#/components/schemas/error_response` **422** — Request is syntactically valid but cannot be processed in its current state. Content-Type: `application/json` ```json { "ucp": { "version": "2026-04-08", "status": "error" }, "messages": [ { "type": "error", "code": "unsupported_currency", "content": "Currency not supported: ZZZ", "severity": "recoverable" } ] } ``` Schema: - schema reference: `#/components/schemas/error_response` **429** — Too many requests. **Security:** requires `bearerAuth`. # Update a checkout session (https://developer.godaddy.com/en/docs/references/rest/shopping/update-checkout) --- title: Update a checkout session description: Replace the writable checkout session state. full: true --- Full description > Replace the writable checkout session state. Send the full `line_items[]` collection on every request. Omitted writable values are cleared, and server-generated fields are ignored. For POS and hardware products, retain the `commerce_location` input. If a submitted product cannot be priced, the response excludes it and includes a `line_item_removed` warning. ## PUT /checkout-sessions/{id} Update a checkout session Replace the writable checkout session state. Send the full `line_items[]` collection on every request. Omitted writable values are cleared, and server-generated fields are ignored. For POS and hardware products, retain the `commerce_location` input. If a submitted product cannot be priced, the response excludes it and includes a `line_item_removed` warning. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `id` | string | yes | The unique identifier of the checkout session. | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `Request-Id` | string | yes | For tracing the request across network layers and components. | | `Idempotency-Key` | string | yes | Ensures duplicate operations don't happen during retries. | ### Request body (required) Content-Type: `application/json` ```json { "line_items": [ { "id": "li_hosting_1", "item": { "id": "hosting-deluxeapi:1mo" }, "quantity": 1 } ], "payment": { "instruments": [ { "id": "profile_mastercard", "handler_id": "com.godaddy.payments", "type": "card", "selected": true } ] } } ``` Schema: - schema reference: `#/components/schemas/checkout_writable_request` ### Responses **200** — Updated checkout session or an error envelope. Content-Type: `application/json` ```json { "ucp": { "version": "2026-04-08", "capabilities": { "dev.ucp.shopping.checkout": [ { "version": "2026-04-08" } ], "com.godaddy.shopping.input": [ { "version": "2026-04-08" } ], "com.godaddy.shopping.catalog_offer": [ { "version": "2026-04-08" } ] }, "payment_handlers": { "com.godaddy.payments": [ { "id": "com.godaddy.payments", "version": "2026-04-08" } ] } }, "id": "d9cf79e3-b39b-4e58-8f30-ddfe1619e969", "line_items": [ { "id": "li_1", "item": { "id": "hosting-deluxeapi:1mo", "title": "Web Hosting Deluxe — 1 Month", "price": 1099 }, "quantity": 1, "totals": [ { "type": "subtotal", "amount": 1099 }, { "type": "total", "amount": 1099 } ] } ], "status": "ready_for_complete", "currency": "USD", "totals": [ { "type": "subtotal", "amount": 1099 }, { "type": "total", "amount": 1099 } ], "links": [ { "type": "privacy_policy", "url": "https://www.godaddy.com/legal/agreements/privacy-policy" }, { "type": "terms_of_service", "url": "https://www.godaddy.com/legal/agreements/terms-of-service" } ], "payment": { "instruments": [ { "id": "profile_visa", "handler_id": "com.godaddy.payments", "type": "card", "selected": true, "display": { "brand": "visa", "last_digits": "4242" } }, { "id": "profile_mastercard", "handler_id": "com.godaddy.payments", "type": "card", "selected": false, "display": { "brand": "mastercard", "last_digits": "4444" } } ] } } ``` Schema: - oneOf(unknown | unknown) **400** — Request validation or caller-correctable business error. Content-Type: `application/json` ```json { "ucp": { "version": "2026-04-08", "status": "error" }, "messages": [ { "type": "error", "code": "invalid_request", "content": "Lookup request must include at least one id.", "severity": "recoverable" } ] } ``` Schema: - schema reference: `#/components/schemas/error_response` **401** — Missing or invalid credentials. **403** — Authenticated credential lacks the required Shopping scope. **404** — Resource does not exist. Content-Type: `application/json` ```json { "ucp": { "version": "2026-04-08", "status": "error" }, "messages": [ { "type": "error", "code": "product_not_found", "content": "Product not found: not-a-real-product", "severity": "unrecoverable" } ] } ``` Schema: - schema reference: `#/components/schemas/error_response` **422** — Request is syntactically valid but cannot be processed in its current state. Content-Type: `application/json` ```json { "ucp": { "version": "2026-04-08", "status": "error" }, "messages": [ { "type": "error", "code": "unsupported_currency", "content": "Currency not supported: ZZZ", "severity": "recoverable" } ] } ``` Schema: - schema reference: `#/components/schemas/error_response` **429** — Too many requests. **Security:** requires `bearerAuth`. # Get store attribute (https://developer.godaddy.com/en/docs/references/rest/stores/get-store-attribute) --- title: Get store attribute description: Returns a single store attribute by name. full: true --- Full description Returns a single store attribute by name. The response is a single-key map of the attribute name to its string value. Allow-listed keys that have not been set return 404; keys outside the per-store allow-list return 400. ## GET /stores/{storeId}/attributes/{attrName} Get store attribute Returns a single store attribute by name. The response is a single-key map of the attribute name to its string value. Allow-listed keys that have not been set return 404; keys outside the per-store allow-list return 400. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `storeId` | unknown | yes | Store ID | | `attrName` | string | yes | Attribute name | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | string | no | Request ID | ### Responses **200** — Store Attribute Found Content-Type: `application/json` Schema: - object — Single-key map of attribute name → value (value is always a string). **400** — Attribute key is not in the store's allow-list. **404** — Store Or Store Attribute Not Found **default** — Error Content-Type: `application/json` Schema: - schema reference: `#/x-ext/852136a` **Security:** requires `PAT`; scopes `commerce.store:read`. # Get store by ID (https://developer.godaddy.com/en/docs/references/rest/stores/get-store-by-id) --- title: Get store by ID description: Retrieve the information of a store using the Business and Store IDs. full: true --- ## GET /stores/{storeId} Get store by ID Retrieve the information of a store using the Business and Store IDs. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `storeId` | unknown | yes | Store ID | ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `includeFields` | array | no | Optional joins to fold into the response. Additive on top of the default field set, not a replacement filter — fields outside this enum are returned unconditionally. Comma-separate values to request multiple joins. Note: the live (v1) gateway exposes this parameter as `includeField` (singular) and accepts repeated parameters. The v2 spelling here is the target shape for when v2 ships. | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | string | no | Request ID | ### Responses **200** — Store Found Content-Type: `application/json` ```json { "id": "a4935421-1995-4b11-8cc3-99c6ad404007", "businessId": "02a17e5b-0897-4d39-9123-b4345163e6df", "displayName": "Global Ventures Apr 22133824", "status": "ACTIVE", "currency": "USD", "timezone": "America/Los_Angeles", "acquirer": "WORLDPAY", "processor": "WORLDPAY", "externalStoreId": "wp-retail-ce5ecce4", "processorData": {}, "attributes": {}, "fixedLocation": true, "mockProcessor": true, "longitude": -122.162, "latitude": 37.4457, "defaultChannelId": "64bdf0cc-02d1-4326-b24e-9e611afc729f", "defaultRetailChannelId": "c884df62-6c3b-4df0-81b7-80b8c4b73bcf", "ownerId": "22264b76-d57b-4eb3-ab4e-1dbe5aeaeed1", "createdAt": "2026-04-22T08:10:26Z", "updatedAt": "2026-04-22T08:10:37Z" } ``` Schema: - schema reference: `#/x-ext/4ba7beb` **default** — Error Content-Type: `application/json` Schema: - schema reference: `#/x-ext/852136a` **Security:** requires `PAT`; scopes `commerce.store:read`. # Tax GraphQL (https://developer.godaddy.com/en/docs/references/rest/taxes) --- title: Tax GraphQL description: Query and mutate taxes and rates on the commerce tax subgraph. full: true --- Store-scoped tax GraphQL over HTTP. Use `commerce.tax:read` to query, `commerce.tax:create` / `commerce.tax:write` / `commerce.tax:delete` to mutate (by operation). See [Commerce API Scopes](https://developer.godaddy.com/docs/references/rest/commerce-scopes). **Endpoint:** `POST /v2/commerce/stores/{storeId}/tax-subgraph` Send the same store ID in the `{storeId}` path and the `x-store-id` header. The header is required. If they differ, the subgraph uses the header. A missing header returns HTTP 200 `AUTHENTICATION_ERROR` (`Failed to authorize`), not HTTP 401\. For `SimpleMoneyInput.value`, send `1999` for $19.99 USD, not `19.99`. Sidebar is grouped by **action/resource**. Expand a resource, then **Query** (`commerce.tax:read`, 8 fields) or **Mutation** (38 fields; scope depends on the verb). The live gateway also exposes `_service`; it is omitted here. ## Example query query Requires `commerce.tax:read`. See [`classification`](https://developer.godaddy.com/docs/references/rest/taxes/classification/queries/classification) for the full schema. ```graphql query GetClassification($id: ID!) { classification(id: $id) { id name label } } ``` ```bash curl -X POST "https://api.godaddy.com/v2/commerce/stores/{storeId}/tax-subgraph" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "Content-Type: application/json" \ -H "x-store-id: {storeId}" \ -d '{ "query": "query GetClassification($id: ID!) { classification(id: $id) { id name label } }", "variables": { "id": "CLASSIFICATION_ID" } }' ``` ## Example mutation mutation Requires `commerce.tax:create`. See [`createRate`](https://developer.godaddy.com/docs/references/rest/taxes/rate/mutations/createRate) for the full schema. ```graphql mutation CreateRate($input: MutationCreateRateInput!) { createRate(input: $input) { id name status } } ``` ```json { "input": { "label": "Sales tax", "value": { "percentage": "8.5" } } } ``` *** ## HTTP reference OpenAPI contract for the subgraph POST (headers, auth, response envelope): ## POST /stores/{storeId}/tax-subgraph Tax GraphQL endpoint Proxies GraphQL to the tax subgraph. Use the `query` field for the GraphQL document and optional `variables` / `operationName`. Send the same store ID in the `{storeId}` path and the `x-store-id` header. The header is required. If they differ, the subgraph uses the header. A missing header returns HTTP 200 with GraphQL `AUTHENTICATION_ERROR` (`Failed to authorize`). ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `storeId` | unknown | yes | | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `x-store-id` | unknown | yes | Required store ID. Send the same value as `{storeId}` in the path. If they differ, the subgraph uses this header. | ### Request body (required) Content-Type: `application/json` ```json { "query": "query GetClassification($id: ID!) { classification(id: $id) { id } }", "variables": { "id": "CLASSIFICATION_ID" } } ``` Schema: - object - `query` (required): string - `variables`: object - `operationName`: string ### Responses **200** — GraphQL response Content-Type: `application/json` Schema: - object - `data`: object - `errors`: array - items: **400** — Invalid request **401** — Unauthorized **403** — Forbidden **404** — Store not found **500** — Internal server error **Security:** requires `PAT`; scopes `commerce.tax:read`, `commerce.tax:create`, `commerce.tax:write`, `commerce.tax:delete`. # Get transaction by ID (https://developer.godaddy.com/en/docs/references/rest/transactions/get-transaction-by-id) --- title: Get transaction by ID description: >- Retrieve all the information for a single transaction using the store and transaction IDs. full: true --- ## GET /stores/{storeId}/transactions/{transactionId} Get transaction by ID Retrieve all the information for a single transaction using the store and transaction IDs. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `storeId` | string | yes | Store unique identifier (UUID format) | | `transactionId` | string | yes | Transaction unique identifier (UUID format) | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `Request Id` | string | no | | ### Responses **200** — Transaction Found Content-Type: `application/json` Schema: - schema reference: `#/x-ext/e438953` **default** — Error Content-Type: `application/json` Schema: - schema reference: `#/x-ext/e2dac50` **Security:** requires `PAT`; scopes `commerce.transaction:read`. # Get all transactions (https://developer.godaddy.com/en/docs/references/rest/transactions/get-transactions) --- title: Get all transactions description: Retrieve all the transactions for a specific store using the store ID. full: true --- ## GET /stores/{storeId}/transactions Get all transactions Retrieve all the transactions for a specific store using the store ID. ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `page` | integer | no | | | `pageSize` | integer | no | | | `totalRequired` | boolean | no | | | `transactionIds` | array | no | Transaction ids to filter | | `updatedAtAfter` | unknown | no | Transaction filter updatedAt start date | | `updatedAtBefore` | unknown | no | Transaction filter updatedAt end date | | `sortBy` | string | no | Transaction sort field | | `sortOrder` | string | no | Transaction sort order | ### Responses **200** — Transactions List Content-Type: `application/json` Schema: - allOf(unknown) - `items`: array - items: **default** — Error Content-Type: `application/json` Schema: - schema reference: `#/x-ext/e2dac50` **Security:** requires `PAT`; scopes `commerce.transaction:read`. # Check availability of multiple domains (https://developer.godaddy.com/en/docs/references/rest/domains/v1/available-bulk) --- title: Check availability of multiple domains description: Checks availability for multiple domains in a single request. full: true --- Full description Checks availability for multiple domains in a single request. Returns an array of availability and pricing results, one per domain queried. ## POST /v1/domains/available Check availability of multiple domains Checks availability for multiple domains in a single request. Returns an array of availability and pricing results, one per domain queried. ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `checkType` | string | no | Optimize for time ('FAST') or accuracy ('FULL') | ### Request body (required) Domain names for which to check availability Content-Type: `application/json` Schema: - array - items: Content-Type: `application/xml` Schema: - array - items: Content-Type: `text/xml` Schema: - array - items: ### Responses **200** — Request was successful Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/DomainAvailableBulk` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/DomainAvailableBulk` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/DomainAvailableBulk` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/DomainAvailableBulk` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/DomainAvailableBulk` **203** — Request was partially successful Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/DomainAvailableBulkMixed` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/DomainAvailableBulkMixed` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/DomainAvailableBulkMixed` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/DomainAvailableBulkMixed` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/DomainAvailableBulkMixed` **400** — Request was malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **422** — - Cannot convert domain label error - Domain is missing IDN script - Domain segment ends with dash - Domain starts with dash - Domain uses unsupported IDN script - FQDN fails generic validity regex - Invalid character(s) error - Invalid tld error - Non-IDN domain name must not have dashes at the third and fourth position - Reserved name error - domain must be specified Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # Check availability of a domain (https://developer.godaddy.com/en/docs/references/rest/domains/v1/available) --- title: Check availability of a domain description: >- Checks whether a single domain is available to register and returns the current price in currency-micro-unit format. full: true --- Full description Checks whether a single domain is available to register and returns the current price in currency-micro-unit format. The definitive flag indicates whether the result came from a live registry query. ## GET /v1/domains/available Check availability of a domain Checks whether a single domain is available to register and returns the current price in currency-micro-unit format. The definitive flag indicates whether the result came from a live registry query. ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `domain` | string | yes | Domain name whose availability is to be checked | | `checkType` | string | no | Optimize for time ('FAST') or accuracy ('FULL') | | `forTransfer` | boolean | no | Whether or not to include domains available for transfer. If set to True, checkType is ignored | ### Responses **200** — Request was successful Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/DomainAvailableResponse` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/DomainAvailableResponse` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/DomainAvailableResponse` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/DomainAvailableResponse` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/DomainAvailableResponse` **400** — Request was malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **422** — - Cannot convert domain label error - Domain is missing IDN script - Domain segment ends with dash - Domain starts with dash - Domain uses unsupported IDN script - FQDN fails generic validity regex - Invalid character(s) error - Invalid tld error - Non-IDN domain name must not have dashes at the third and fourth position - Reserved name error - domain must be specified Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # Cancel a purchased domain (https://developer.godaddy.com/en/docs/references/rest/domains/v1/cancel) --- title: Cancel a purchased domain description: >- Cancels a purchased domain and initiates a refund if within the cancellation window. full: true --- Full description Cancels a purchased domain and initiates a refund if within the cancellation window. This action is irreversible. ## DELETE /v1/domains/{domain} Cancel a purchased domain Cancels a purchased domain and initiates a refund if within the cancellation window. This action is irreversible. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `domain` | string | yes | Domain to cancel | ### Responses **200** — Request was successful **400** — Request was malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **404** — The domain does not exist Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **422** — - Unknown domain error - At least two apex (aka @) `nameServers` must be specified Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # Validate a domain contact request body (https://developer.godaddy.com/en/docs/references/rest/domains/v1/contacts-validate) --- title: Validate a domain contact request body description: >- Validates contact information against the domain-level rules for each domain in the domains list. full: true --- Full description Validates contact information against the domain-level rules for each domain in the domains list. Pass tlds as an alternative, except for .uk domains which require full domain names. ## POST /v1/domains/contacts/validate Validate a domain contact request body Validates contact information against the domain-level rules for each domain in the domains list. Pass tlds as an alternative, except for .uk domains which require full domain names. ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `marketId` | string | no | MarketId in which the request is being made, and for which responses should be localized | ### Request body (required) An instance document expected for domains contacts validation Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/DomainsContactsBulk` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/DomainsContactsBulk` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/DomainsContactsBulk` ### Responses **200** — No response was specified **204** — Request was successful **400** — Request was malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **422** — Request body doesn't fulfill schema, see details in `fields` Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorDomainContactsValidate` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/ErrorDomainContactsValidate` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/ErrorDomainContactsValidate` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/ErrorDomainContactsValidate` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/ErrorDomainContactsValidate` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # Get required legal agreements for a TLD (https://developer.godaddy.com/en/docs/references/rest/domains/v1/get-agreement) --- title: Get required legal agreements for a TLD description: >- Returns the TLD-specific legal agreements that must be accepted before purchase or transfer. full: true --- Full description Returns the TLD-specific legal agreements that must be accepted before purchase or transfer. The agreementKeys from this response are required in the consent object. ## GET /v1/domains/agreements Get required legal agreements for a TLD Returns the TLD-specific legal agreements that must be accepted before purchase or transfer. The agreementKeys from this response are required in the consent object. ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `tlds` | array | yes | list of TLDs whose legal agreements are to be retrieved | | `v1-privacy` | boolean | yes | Whether or not privacy has been requested | | `forTransfer` | boolean | no | Whether or not domain tranfer has been requested | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Market-Id` | string | no | Unique identifier of the Market used to retrieve/translate Legal Agreements | ### Responses **200** — Request was successful Content-Type: `application/json` Schema: - array - items: Content-Type: `application/javascript` Schema: - array - items: Content-Type: `application/xml` Schema: - array - items: Content-Type: `text/javascript` Schema: - array - items: Content-Type: `text/xml` Schema: - array - items: **400** — Request was malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **404** — Resource not found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # Retrieve details for the specified Domain (https://developer.godaddy.com/en/docs/references/rest/domains/v1/get) --- title: Retrieve details for the specified Domain description: >- Returns the full DomainDetail object including status, contacts, nameservers, lock state, privacy flag, and expiration timestamp. full: true --- ## GET /v1/domains/{domain} Retrieve details for the specified Domain Returns the full DomainDetail object including status, contacts, nameservers, lock state, privacy flag, and expiration timestamp. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `domain` | string | yes | Domain name whose details are to be retrieved | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Shopper-Id` | string | no | Shopper ID which owns the domain. NOTE: This is only required if you are a Reseller managing a domain purchased outside the scope of your reseller account. | ### Responses **200** — Request was successful Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/DomainDetail` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/DomainDetail` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/DomainDetail` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/DomainDetail` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/DomainDetail` **203** — Request was partially successful, see verifications.status for further detail Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/DomainDetail` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/DomainDetail` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/DomainDetail` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/DomainDetail` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/DomainDetail` **400** — Request was malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **404** — Resource not found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **422** — `domain` must be specified Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # Domains v1 (https://developer.godaddy.com/en/docs/references/rest/domains/v1) --- title: Domains v1 description: >- Account-scoped Domains operations under /v1/domains. Search, register, list, DNS, privacy, renewals, and transfer. --- ## Overview The `v1` namespace exposes Domains operations that act on the domains owned by the authenticated account. Caller identity is established by the `Authorization` header alone; some operations also accept an `X-Shopper-Id` header to act on behalf of a specific shopper. The `v1` namespace is account-scoped; use `v2` when you need async operation tracking (action queues, status polling, and notifications). For a task-shaped guide layered on top of these endpoints, see [Use the API → Domains](https://developer.godaddy.com/docs/api-users/domains/manage). The complete OpenAPI spec for the v1 namespace is available at [/openapi/domains-v1.json](https://developer.godaddy.com/openapi/domains-v1.json) — useful for code generation, SDK tooling, and LLM context. ## Operation groups The v1 namespace is organized into five operation groups, each rendered on its own reference page below. ## Authentication and scopes Every v1 operation requires an `Authorization` header carrying a Personal Access Token (Bearer) or a legacy `sso-key` credential. PATs use the granular Domains & DNS scopes listed in [Authentication](https://developer.godaddy.com/docs/api-users/auth), like `domains.domain:read`, `domains.domain:update`, `domains.dns:update`, and `domains.transfer:execute`. ## Conventions | Concern | Where it's documented | | ----------------------------------------------- | ------------------------------------------ | | Error envelope and retry semantics | [Errors](https://developer.godaddy.com/docs/api-users/errors) | | Rate limits (60 requests/minute per credential) | [Rate limits](https://developer.godaddy.com/docs/api-users/rate-limits) | | Cursor-based pagination on `GET /v1/domains` | [Pagination](https://developer.godaddy.com/docs/api-users/pagination) | # Retrieve a list of Domains for the specified Shopper (https://developer.godaddy.com/en/docs/references/rest/domains/v1/list) --- title: Retrieve a list of Domains for the specified Shopper description: Returns a paginated list of domains owned by the authenticated account. full: true --- Full description Returns a paginated list of domains owned by the authenticated account. Supports filtering by status and optional inclusion of contacts, nameservers, and authCode in each record. ## GET /v1/domains Retrieve a list of Domains for the specified Shopper Returns a paginated list of domains owned by the authenticated account. Supports filtering by status and optional inclusion of contacts, nameservers, and authCode in each record. ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `statuses` | array | no | Only include results with `status` value in the specified set | | `statusGroups` | array | no | Only include results with `status` value in any of the specified groups | | `limit` | integer | no | Maximum number of domains to return | | `marker` | string | no | Marker Domain to use as the offset in results | | `includes` | array | no | Optional details to be included in the response | | `modifiedDate` | string | no | Only include results that have been modified since the specified date | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Shopper-Id` | string | no | Shopper ID which owns the domain. NOTE: This is only required if you are a Reseller managing a domain purchased outside the scope of your reseller account. | ### Responses **200** — Request was successful Content-Type: `application/json` Schema: - array - items: Content-Type: `application/javascript` Schema: - array - items: Content-Type: `application/xml` Schema: - array - items: Content-Type: `text/javascript` Schema: - array - items: Content-Type: `text/xml` Schema: - array - items: **400** — Request was malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **422** — Limit must have a value no greater than 1000 Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # Purchase and register the specified Domain (https://developer.godaddy.com/en/docs/references/rest/domains/v1/purchase) --- title: Purchase and register the specified Domain description: Registers the specified domain. full: true --- Full description Registers the specified domain. Requires a consent object with agreement keys from GET /v1/domains/agreements. Charges the account's billing method. ## POST /v1/domains/purchase Purchase and register the specified Domain Registers the specified domain. Requires a consent object with agreement keys from GET /v1/domains/agreements. Charges the account's billing method. ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Shopper-Id` | string | no | Shopper ID which owns the domain. NOTE: This is only required if you are a Reseller managing a domain purchased outside the scope of your reseller account. | ### Responses **200** — Request was successful Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/DomainPurchaseResponse` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/DomainPurchaseResponse` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/DomainPurchaseResponse` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/DomainPurchaseResponse` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/DomainPurchaseResponse` **400** — Request was malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **404** — Resource not found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **422** — - domain must be specified - Based on restrictions declared in JSON schema returned by `./schema/{tld}` - Cannot convert domain label error - Domain is missing IDN script - Domain segment ends with dash - Domain starts with dash - Domain uses unsupported IDN script - FQDN fails generic validity regex - Invalid character(s) error - Invalid tld error - Non-IDN domain name must not have dashes at the third and fourth position - Reserved name error - `body` must be specified Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # Add the specified DNS Records to the specified Domain (https://developer.godaddy.com/en/docs/references/rest/domains/v1/record-add) --- title: Add the specified DNS Records to the specified Domain description: Appends DNS records to the domain's zone without removing existing records. full: true --- Full description Appends DNS records to the domain's zone without removing existing records. Existing records with the same type and name are preserved. Returns 204 No Content. ## PATCH /v1/domains/{domain}/records Add the specified DNS Records to the specified Domain Appends DNS records to the domain's zone without removing existing records. Existing records with the same type and name are preserved. Returns 204 No Content. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `domain` | string | yes | Domain whose DNS Records are to be augmented | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Shopper-Id` | string | no | Shopper ID which owns the domain. NOTE: This is only required if you are a Reseller managing a domain purchased outside the scope of your reseller account. | ### Request body (required) DNS Records to add to whatever currently exists Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ArrayOfDNSRecord` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/ArrayOfDNSRecord` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/ArrayOfDNSRecord` ### Responses **200** — Request was successful **400** — Request was malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **404** — Resource not found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **422** — `domain` is not a valid Domain name Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **504** — Gateway timeout Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # Delete DNS records by type and name (https://developer.godaddy.com/en/docs/references/rest/domains/v1/record-delete-type-name) --- title: Delete DNS records by type and name description: Deletes all DNS records matching the specified type and name. full: true --- Full description Deletes all DNS records matching the specified type and name. All other records are preserved. Returns 204 No Content. ## DELETE /v1/domains/{domain}/records/{type}/{name} Delete DNS records by type and name Deletes all DNS records matching the specified type and name. All other records are preserved. Returns 204 No Content. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `domain` | string | yes | Domain whose DNS Records are to be deleted | | `type` | string | yes | DNS Record Type for which DNS Records are to be deleted | | `name` | string | yes | DNS Record Name for which DNS Records are to be deleted | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Shopper-Id` | string | no | Shopper ID which owns the domain. NOTE: This is only required if you are a Reseller managing a domain purchased outside the scope of your reseller account. | ### Responses **204** — Request was successful **400** — Request was malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **404** — Domain not found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **409** — The given domain is not eligible to have its records changed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **422** — `domain` is not a valid Domain name Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **504** — Gateway timeout Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # List DNS records for a domain (https://developer.godaddy.com/en/docs/references/rest/domains/v1/record-get) --- title: List DNS records for a domain description: Returns DNS records for the domain. full: true --- Full description Returns DNS records for the domain. Optionally filter by record type and name. Returns an array of DNSRecord objects. ## GET /v1/domains/{domain}/records/{type}/{name} List DNS records for a domain Returns DNS records for the domain. Optionally filter by record type and name. Returns an array of DNSRecord objects. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `domain` | string | yes | Domain whose DNS Records are to be retrieved | | `type` | string | yes | DNS Record Type for which DNS Records are to be retrieved | | `name` | string | yes | DNS Record Name for which DNS Records are to be retrieved | ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `offset` | integer | no | Number of results to skip for pagination | | `limit` | integer | no | Maximum number of items to return | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Shopper-Id` | string | no | Shopper ID which owns the domain. NOTE: This is only required if you are a Reseller managing a domain purchased outside the scope of your reseller account. | ### Responses **200** — Request was successful Content-Type: `application/json` Schema: - array - items: Content-Type: `application/javascript` Schema: - array - items: Content-Type: `application/xml` Schema: - array - items: Content-Type: `text/javascript` Schema: - array - items: Content-Type: `text/xml` Schema: - array - items: **400** — Request was malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **404** — Resource not found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **422** — - `record` does not fulfill the schema - `domain` is not a valid Domain name Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **504** — Gateway timeout Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # Replace DNS records by type and name (https://developer.godaddy.com/en/docs/references/rest/domains/v1/record-replace-type-name) --- title: Replace DNS records by type and name description: Replaces all DNS records of the specified type and name. full: true --- Full description Replaces all DNS records of the specified type and name. All other records are preserved. Returns 204 No Content. ## PUT /v1/domains/{domain}/records/{type}/{name} Replace DNS records by type and name Replaces all DNS records of the specified type and name. All other records are preserved. Returns 204 No Content. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `domain` | string | yes | Domain whose DNS Records are to be replaced | | `type` | string | yes | DNS Record Type for which DNS Records are to be replaced | | `name` | string | yes | DNS Record Name for which DNS Records are to be replaced | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Shopper-Id` | string | no | Shopper ID which owns the domain. NOTE: This is only required if you are a Reseller managing a domain purchased outside the scope of your reseller account. | ### Request body (required) DNS Records to replace whatever currently exists Content-Type: `application/json` Schema: - array - items: Content-Type: `application/xml` Schema: - array - items: Content-Type: `text/xml` Schema: - array - items: ### Responses **200** — Request was successful **400** — Request was malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **404** — Resource not found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **422** — `record` does not fulfill the schema Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **504** — Gateway timeout Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # Replace DNS records by type (https://developer.godaddy.com/en/docs/references/rest/domains/v1/record-replace-type) --- title: Replace DNS records by type description: Replaces all DNS records of the specified type across all names. full: true --- Full description Replaces all DNS records of the specified type across all names. Records of other types are preserved. Returns 204 No Content. ## PUT /v1/domains/{domain}/records/{type} Replace DNS records by type Replaces all DNS records of the specified type across all names. Records of other types are preserved. Returns 204 No Content. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `domain` | string | yes | Domain whose DNS Records are to be replaced | | `type` | string | yes | DNS Record Type for which DNS Records are to be replaced | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Shopper-Id` | string | no | Shopper ID which owns the domain. NOTE: This is only required if you are a Reseller managing a domain purchased outside the scope of your reseller account. | ### Request body (required) DNS Records to replace whatever currently exists Content-Type: `application/json` Schema: - array - items: Content-Type: `application/xml` Schema: - array - items: Content-Type: `text/xml` Schema: - array - items: ### Responses **200** — Request was successful **400** — Request was malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **404** — Resource not found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **422** — `record` does not fulfill the schema Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **504** — Gateway timeout Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # Replace all DNS Records for the specified Domain (https://developer.godaddy.com/en/docs/references/rest/domains/v1/record-replace) --- title: Replace all DNS Records for the specified Domain description: Replaces the entire DNS record set for the domain. full: true --- Full description Replaces the entire DNS record set for the domain. All existing records are removed and replaced with the submitted set. Returns 204 No Content. ## PUT /v1/domains/{domain}/records Replace all DNS Records for the specified Domain Replaces the entire DNS record set for the domain. All existing records are removed and replaced with the submitted set. Returns 204 No Content. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `domain` | string | yes | Domain whose DNS Records are to be replaced | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Shopper-Id` | string | no | Shopper ID which owns the domain. NOTE: This is only required if you are a Reseller managing a domain purchased outside the scope of your reseller account. | ### Request body (required) DNS Records to replace whatever currently exists Content-Type: `application/json` Schema: - array - items: Content-Type: `application/xml` Schema: - array - items: Content-Type: `text/xml` Schema: - array - items: ### Responses **200** — Request was successful **400** — Request was malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **404** — Resource not found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **422** — - `domain` is not a valid Domain name - `record` does not fulfill the schema Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **504** — Gateway timeout Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # Renew the specified Domain (https://developer.godaddy.com/en/docs/references/rest/domains/v1/renew) --- title: Renew the specified Domain description: 'Renews the domain for the specified period, extending the expiration date.' full: true --- Full description Renews the domain for the specified period, extending the expiration date. Charges the account's billing method. ## POST /v1/domains/{domain}/renew Renew the specified Domain Renews the domain for the specified period, extending the expiration date. Charges the account's billing method. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `domain` | string | yes | Domain to renew | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Shopper-Id` | string | no | Shopper ID which owns the domain. NOTE: This is only required if you are a Reseller managing a domain purchased outside the scope of your reseller account. | ### Request body Options for renewing existing Domain Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/DomainRenew` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/DomainRenew` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/DomainRenew` ### Responses **200** — Request was successful Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/DomainPurchaseResponse` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/DomainPurchaseResponse` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/DomainPurchaseResponse` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/DomainPurchaseResponse` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/DomainPurchaseResponse` **400** — Request was malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **404** — Resource not found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **409** — The domain status does not allow performing the operation Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **422** — - End-user must read and consent to all of the following legal agreements - `domain` must match `sld.tld` Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # Get the registration schema for a TLD (https://developer.godaddy.com/en/docs/references/rest/domains/v1/schema) --- title: Get the registration schema for a TLD description: >- Returns the JSON schema for the domain purchase request body for the specified TLD. full: true --- Full description Returns the JSON schema for the domain purchase request body for the specified TLD. Fetch before purchasing to identify required fields and TLD-specific constraints. ## GET /v1/domains/purchase/schema/{tld} Get the registration schema for a TLD Returns the JSON schema for the domain purchase request body for the specified TLD. Fetch before purchasing to identify required fields and TLD-specific constraints. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `tld` | string | yes | The Top-Level Domain whose schema should be retrieved | ### Responses **200** — Request was successful Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/JsonSchema` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/JsonSchema` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/JsonSchema` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/JsonSchema` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/JsonSchema` **400** — Request was malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **404** — Resource not found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **422** — `tld` must be specified Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # Suggest alternate domain names (https://developer.godaddy.com/en/docs/references/rest/domains/v1/suggest) --- title: Suggest alternate domain names description: >- Returns domain name suggestions based on a seed domain, keywords, or purchase history. full: true --- Full description Returns domain name suggestions based on a seed domain, keywords, or purchase history. Useful for presenting alternatives when a desired domain is unavailable. ## GET /v1/domains/suggest Suggest alternate domain names Returns domain name suggestions based on a seed domain, keywords, or purchase history. Useful for presenting alternatives when a desired domain is unavailable. ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `query` | string | no | Domain name or set of keywords for which alternative domain names will be suggested | | `country` | string | no | Two-letter ISO country code to be used as a hint for target region NOTE: These are sample values, there are many more | | `city` | string | no | Name of city to be used as a hint for target region | | `sources` | array | no | Sources to be queried - **CC_TLD** — Varies the TLD using Country Codes - **EXTENSION** — Varies the TLD - **KEYWORD_SPIN** — Identifies keywords and then rotates each one - **PREMIUM** — Includes variations with premium prices | | `tlds` | array | no | Top-level domains to be included in suggestions NOTE: These are sample values, there are many more | | `lengthMax` | integer | no | Maximum length of second-level domain | | `lengthMin` | integer | no | Minimum length of second-level domain | | `limit` | integer | no | Maximum number of suggestions to return | | `waitMs` | integer | no | Maximum amount of time, in milliseconds, to wait for responses If elapses, return the results compiled up to that point | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Shopper-Id` | string | no | Shopper ID which owns the domain. NOTE: This is only required if you are a Reseller managing a domain purchased outside the scope of your reseller account. | ### Responses **200** — Request was successful Content-Type: `application/json` Schema: - array - items: Content-Type: `application/javascript` Schema: - array - items: Content-Type: `application/xml` Schema: - array - items: Content-Type: `text/javascript` Schema: - array - items: Content-Type: `text/xml` Schema: - array - items: **400** — Request was malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **404** — Resource not found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **422** — `query` must be specified Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **504** — Gateway timeout Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # Retrieves a list of TLDs supported and enabled for sale (https://developer.godaddy.com/en/docs/references/rest/domains/v1/tlds) --- title: Retrieves a list of TLDs supported and enabled for sale description: >- Returns all TLDs currently available for registration, including pricing and any eligibility requirements. full: true --- ## GET /v1/domains/tlds Retrieves a list of TLDs supported and enabled for sale Returns all TLDs currently available for registration, including pricing and any eligibility requirements. ### Responses **200** — Request was successful Content-Type: `application/json` Schema: - array - items: Content-Type: `application/javascript` Schema: - array - items: Content-Type: `application/xml` Schema: - array - items: Content-Type: `text/javascript` Schema: - array - items: Content-Type: `text/xml` Schema: - array - items: **400** — Request was malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # Purchase and start or restart transfer process (https://developer.godaddy.com/en/docs/references/rest/domains/v1/transfer-in) --- title: Purchase and start or restart transfer process description: Initiates an inbound domain transfer from another registrar. full: true --- Full description Initiates an inbound domain transfer from another registrar. Requires an authcode and a consent object with agreement keys. Charges a transfer fee. ## POST /v1/domains/{domain}/transfer Purchase and start or restart transfer process Initiates an inbound domain transfer from another registrar. Requires an authcode and a consent object with agreement keys. Charges a transfer fee. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `domain` | string | yes | Domain to transfer in | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Shopper-Id` | string | no | Shopper ID which owns the domain. NOTE: This is only required if you are a Reseller managing a domain purchased outside the scope of your reseller account. | ### Request body (required) Details for domain transfer purchase Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/DomainTransferIn` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/DomainTransferIn` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/DomainTransferIn` ### Responses **200** — Request was successful Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/DomainPurchaseResponse` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/DomainPurchaseResponse` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/DomainPurchaseResponse` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/DomainPurchaseResponse` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/DomainPurchaseResponse` **400** — Request was malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **409** — `domain` (domain) isn't available for transfer Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **422** — - Based on restrictions declared in JSON schema returned by `./schema/{tld}` - Cannot convert domain label error - Domain is missing IDN script - Domain segment ends with dash - Domain starts with dash - Domain uses unsupported IDN script - End-user must read and consent to all of the following legal agreements - FQDN fails generic validity regex - Invalid character(s) error - Invalid period range - Invalid tld error - Non-IDN domain name must not have dashes at the third and fourth position - Reserved name error - `authCode` cannot be empty - `domain` must match `sld.tld` - domain must be specified Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # Update domain (https://developer.godaddy.com/en/docs/references/rest/domains/v1/update-contacts) --- title: Update domain description: Updates domain settings. full: true --- Full description Updates domain settings. Only fields included in the request body are modified. Returns 204 No Content. ## PATCH /v1/domains/{domain}/contacts Update domain Updates domain settings. Only fields included in the request body are modified. Returns 204 No Content. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `domain` | string | yes | Domain whose Contacts are to be updated. | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Shopper-Id` | string | no | Shopper ID which owns the domain. NOTE: This is only required if you are a Reseller managing a domain purchased outside the scope of your reseller account. | ### Request body (required) Changes to apply to existing Contacts Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/DomainContacts` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/DomainContacts` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/DomainContacts` ### Responses **200** — No response was specified **204** — Request was successful **400** — Request was malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **404** — - Domain not found - Identity document not found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **422** — `domain` is not a valid Domain name Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **504** — Gateway timeout Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # Update details for the specified Domain (https://developer.godaddy.com/en/docs/references/rest/domains/v1/update) --- title: Update details for the specified Domain description: Updates one or more fields on the domain. full: true --- Full description Updates one or more fields on the domain. Accepts a partial DomainUpdate body - only fields included are modified. Returns 204 No Content. ## PATCH /v1/domains/{domain} Update details for the specified Domain Updates one or more fields on the domain. Accepts a partial DomainUpdate body - only fields included are modified. Returns 204 No Content. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `domain` | string | yes | Domain whose details are to be updated | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Shopper-Id` | string | no | Shopper ID which owns the domain. NOTE: This is only required if you are a Reseller managing a domain purchased outside the scope of your reseller account. | ### Request body (required) Changes to apply to existing Domain Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/DomainUpdate` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/DomainUpdate` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/DomainUpdate` ### Responses **200** — Request was successful **400** — Request was malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **403** — Specified Subaccount not owned by authenticated Shopper Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **404** — Resource not found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **409** — The given domain is not eligible to have its nameservers changed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **422** — - At least two apex (aka @) `nameServers` must be specified - Failed to update nameservers Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # Validate a domain purchase request body (https://developer.godaddy.com/en/docs/references/rest/domains/v1/validate) --- title: Validate a domain purchase request body description: >- Validates a purchase request body against the TLD schema with no side effects and no charge. full: true --- Full description Validates a purchase request body against the TLD schema with no side effects and no charge. Returns 200 on success. ## POST /v1/domains/purchase/validate Validate a domain purchase request body Validates a purchase request body against the TLD schema with no side effects and no charge. Returns 200 on success. ### Responses **200** — Request was successful **400** — Request was malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **404** — Resource not found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **422** — Based on restrictions declared in JSON schema returned by `./schema/{tld}` Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # Re-send Contact E-mail Verification for specified Domain (https://developer.godaddy.com/en/docs/references/rest/domains/v1/verify-email) --- title: Re-send Contact E-mail Verification for specified Domain description: >- Re-sends the ICANN registrant email verification to the domain's registrant contact. full: true --- Full description Re-sends the ICANN registrant email verification to the domain's registrant contact. Use when the original verification email was not received or has expired. ## POST /v1/domains/{domain}/verifyRegistrantEmail Re-send Contact E-mail Verification for specified Domain Re-sends the ICANN registrant email verification to the domain's registrant contact. Use when the original verification email was not received or has expired. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `domain` | string | yes | Domain whose Contact E-mail should be verified. | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Shopper-Id` | string | no | Shopper ID which owns the domain. NOTE: This is only required if you are a Reseller managing a domain purchased outside the scope of your reseller account. | ### Responses **200** — Request was successful **400** — Request was malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **404** — Resource not found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **422** — `domain` is not a valid Domain name Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/ErrorLimit` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **504** — Gateway timeout Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `application/xml` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/javascript` Schema: - schema reference: `#/components/schemas/Error` Content-Type: `text/xml` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # Domain Actions (https://developer.godaddy.com/en/docs/references/rest/domains/v2/domain-actions) --- title: Domain Actions description: >- Poll the status and cancel asynchronous operations queued by domain write requests. full: true --- ## GET /v2/customers/{customerId}/domains/{domain}/actions Retrieves a list of the most recent actions for the specified domain Returns a paginated list of recent actions for the domain. Use to track long-running operations or audit domain history. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `customerId` | string | yes | The Customer identifier. Note: For API Resellers, performing actions on behalf of your customers, you need to specify the Subaccount customer identifier you're operating on behalf of. | | `domain` | string | yes | Domain whose actions are to be retrieved | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | string | no | A client provided identifier for tracking this request. | ### Responses **200** — Request was successful Content-Type: `application/json` Schema: - array - items: **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — The domain does not exist Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. ## GET /v2/customers/{customerId}/domains/{domain}/actions/{type} Retrieves the most recent action for the specified domain Returns the most recent action of the specified type including status, timestamps, and any error details. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `customerId` | string | yes | The Customer identifier. Note: For API Resellers, performing actions on behalf of your customers, you need to specify the Subaccount customer identifier you're operating on behalf of. | | `domain` | string | yes | Domain whose action is to be retrieved | | `type` | string | yes | The type of action to retrieve | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | string | no | A client provided identifier for tracking this request. | ### Responses **200** — Request was successful Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Action` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — The domain does not exist Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **409** — The domain status does not allow performing the operation Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. ## DELETE /v2/customers/{customerId}/domains/{domain}/actions/{type} Cancel the most recent user action for the specified domain Cancels the most recent user-initiated action if it is still in a cancellable state. Returns 202 Accepted. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `customerId` | string | yes | The Customer identifier. Note: For API Resellers, performing actions on behalf of your customers, you need to specify the Subaccount customer identifier you're operating on behalf of. | | `domain` | string | yes | Domain whose action is to be cancelled | | `type` | string | yes | The type of action to cancel | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | string | no | A client provided identifier for tracking this request. | ### Responses **204** — Request was successful **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — The domain does not exist Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **409** — The action status does not allow performing the operation Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # Domain Notifications (https://developer.godaddy.com/en/docs/references/rest/domains/v2/domain-notifications) --- title: Domain Notifications description: >- Manage notification opt-in preferences, retrieve notification schemas, and acknowledge domain lifecycle notifications. full: true --- ## GET /v2/customers/{customerId}/domains/notifications Retrieve the next domain notification Returns the next unacknowledged domain notification. Returns 200 with a Notification body, or 204 if no notifications are pending. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `customerId` | string | yes | The Customer identifier. Note: For API Resellers, performing actions on behalf of your customers, you need to specify the Subaccount customer identifier you're operating on behalf of. | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | string | no | A client provided identifier for tracking this request. | ### Responses **200** — Request was successful Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/DomainNotification` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — The customer does not exist Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. ## GET /v2/customers/{customerId}/domains/notifications/optIn Retrieve a list of notification types that are opted in Returns the notification types the account is currently opted in to receive. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `customerId` | string | yes | The Customer identifier. Note: For API Resellers, performing actions on behalf of your customers, you need to specify the Subaccount customer identifier you're operating on behalf of. | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | string | no | A client provided identifier for tracking this request. | ### Responses **200** — Request was successful Content-Type: `application/json` Schema: - array - items: **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — The customer does not exist Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. ## PUT /v2/customers/{customerId}/domains/notifications/optIn Opt in to receive notifications for the submitted notification types Opts the account in to receiving the specified notification types. Returns 204 No Content. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `customerId` | string | yes | The Customer identifier. Note: For API Resellers, performing actions on behalf of your customers, you need to specify the Subaccount customer identifier you're operating on behalf of. | ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `types` | array | yes | The notification types that should be opted in | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | string | no | A client provided identifier for tracking this request. | ### Responses **204** — Command successful **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — The customer does not exist Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **422** — `type` must be specified Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. ## GET /v2/customers/{customerId}/domains/notifications/schemas/{type} Retrieve the schema for the notification data for the specified notification type Returns the JSON schema for a specific notification type's data payload. Use to validate or parse notification data before processing. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `customerId` | string | yes | The Customer identifier. Note: For API Resellers, performing actions on behalf of your customers, you need to specify the Subaccount customer identifier you're operating on behalf of. | | `type` | string | yes | The notification type whose schema should be retrieved | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | string | no | A client provided identifier for tracking this request. | ### Responses **200** — Request was successful Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/JsonSchema` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — The schema type does not exist Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **422** — `type` must be specified Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. ## POST /v2/customers/{customerId}/domains/notifications/{notificationId}/acknowledge Acknowledge a domain notification Acknowledges a domain notification, removing it from the notification queue. Returns 204 No Content. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `customerId` | string | yes | The Customer identifier. Note: For API Resellers, performing actions on behalf of your customers, you need to specify the Subaccount customer identifier you're operating on behalf of. | | `notificationId` | string | yes | The notification ID to acknowledge | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | string | no | A client provided identifier for tracking this request. | ### Responses **204** — Message acknowledged **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — The domain does not exist Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # Domains API Usage (https://developer.godaddy.com/en/docs/references/rest/domains/v2/domains-api-usage) --- title: Domains API Usage description: >- Retrieve monthly API request usage counts for your account. Data is retained for three months. full: true --- ## GET /v2/domains/usage/{yyyymm} Retrieve api usage request counts for a specific year/month. The data is retained for a period of three months. Returns monthly API request counts for the account. Data is retained for three months. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `yyyymm` | string | yes | The year/month timeframe for the request counts (in the format yyyy-mm) | ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `includes` | array | no | Determines if the detail records (grouped by request path) are included in the response | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | string | no | A client provided identifier for tracking this request. | ### Responses **200** — Request was successful Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/UsageMonthly` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # Domains v2 (https://developer.godaddy.com/en/docs/references/rest/domains/v2) --- title: Domains v2 description: >- Domains v2 — v1 capabilities plus async operation tracking. Action queues, status polling, notifications, forwarding, and registration under /v2/customers/{customerId}/domains. --- ## Overview The `v2` namespace extends the Domains API with async operation tracking — action queues, status polling, and lifecycle notifications. Operation paths follow `/v2/customers/{customerId}/domains/...`. Use `v2` when you need to track long-running writes (transfers, redemptions) that return `202 Accepted` instead of completing synchronously. For a task-shaped guide layered on top of these endpoints, see [Use the API → Domains](https://developer.godaddy.com/docs/api-users/domains/manage). The complete OpenAPI spec for the v2 namespace is available at [/openapi/domains-v2.json](https://developer.godaddy.com/openapi/domains-v2.json) — useful for code generation, SDK tooling, and LLM context. ## Operation groups The v2 namespace is organized into seven operation groups, each rendered on its own reference page below. ## Authentication and scopes Every v2 operation requires an `Authorization` header carrying a Personal Access Token (Bearer) or a legacy `sso-key` credential. The principal must additionally be authorized for the customer named in the URL. PATs use the granular Domains & DNS scopes listed in [Authentication](https://developer.godaddy.com/docs/api-users/auth), including `domains.domain:read`, `domains.domain:update`, and `domains.transfer:execute`. ## Find your customer ID API Resellers acting on behalf of a customer pass that subaccount's `customerId`, not their own. Resolve it with the same lookup, substituting the subaccount's shopper ID. ## v2-only capabilities Some operations have no v1 equivalent and must be reached through `v2`: * **Domain forwarding** (HTTP redirects on a domain). * **Notification subscriptions** (lifecycle events delivered to a callback or pulled on demand). * **Customer-scoped change-of-registrant** (managed across customer boundaries). ## Conventions | Concern | Where it's documented | | ---------------------------------------------------- | -------------------------------------------------------------------- | | Error envelope and retry semantics | [Errors](https://developer.godaddy.com/docs/api-users/errors) | | Rate limits (60 requests/minute per credential) | [Rate limits](https://developer.godaddy.com/docs/api-users/rate-limits) | | Asynchronous-write polling via the `Action` resource | [Actions reference](https://developer.godaddy.com/docs/references/rest/domains/v2/domain-actions) | # Manage Domain Settings (https://developer.godaddy.com/en/docs/references/rest/domains/v2/manage-domain-settings) --- title: Manage Domain Settings description: >- Retrieve domain details and manage contacts, nameservers, forwarding rules, privacy forwarding, renewals, and redemption. full: true --- ## GET /v2/customers/{customerId}/domains/{domain}/changeOfRegistrant Retrieve change of registrant information Returns current change of registrant details including status, requested contacts, and any pending approvals. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `customerId` | string | yes | The Customer identifier. Note: For API Resellers, performing actions on behalf of your customers, you need to specify the Subaccount customer identifier you're operating on behalf of. | | `domain` | string | yes | Domain whose change of registrant information is to be retrieved | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | string | no | A client provided identifier for tracking this request. | ### Responses **200** — Request was successful Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/DomainChangeOfRegistrant` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — The contact does not exist Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **409** — There is already a similar action processing Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **422** — `domain` must be specified Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **502** — Dependent service unavailable Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. ## DELETE /v2/customers/{customerId}/domains/{domain}/changeOfRegistrant Cancel a pending change of registrant request Cancels a pending change of registrant. Returns 202 - poll GET .../actions/CHANGE_OF_REGISTRANT_DELETE until COMPLETED, FAILED, or CANCELLED. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `customerId` | string | yes | The Customer identifier. Note: For API Resellers, performing actions on behalf of your customers, you need to specify the Subaccount customer identifier you're operating on behalf of. | | `domain` | string | yes | Domain whose change of registrant is to be cancelled | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | string | no | A client provided identifier for tracking this request. | ### Responses **202** — Request Accepted. You may use GET /v2/customers/{customerId}/domains/{domain}/actions/CHANGE_OF_REGISTRANT_DELETE to poll status **401** — Authentication info not sent or invalid Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` **404** — The contact does not exist Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` **409** — There is already a similar action processing Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` **422** — `domain` must be specified Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` **502** — Dependent service unavailable Content-Type: `*/*` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. ## PUT /v2/customers/{customerId}/domains/{domain}/nameServers Replaces the existing name servers on the domain. Replaces the domain's authoritative nameservers. Returns 202 - poll GET .../actions/DOMAIN_UPDATE_NAME_SERVERS until the action reaches a terminal state. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `customerId` | string | yes | The Customer identifier. Note: For API Resellers, performing actions on behalf of your customers, you need to specify the Subaccount customer identifier you're operating on behalf of. | | `domain` | string | yes | Domain whose name servers are to be replaced | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | string | no | A client provided identifier for tracking this request. | ### Request body (required) Name server records to replace on the domain Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/DomainNameServerUpdateV2` ### Responses **202** — Request Accepted. You may use GET /v2/customers/{customerId}/domains/{domain}/actions/DOMAIN_UPDATE_NAME_SERVERS to poll status **400** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **401** — Request was malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — The domain does not exist Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **409** — There is already a similar action processing Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **422** — Request body doesn't fulfill schema, see details in `fields` Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. ## GET /v2/customers/{customerId}/domains/{domain} Retrieve details for the specified Domain Returns the full DomainDetailV2 object including status, contacts, nameservers, lock state, privacy flag, and expiration timestamp. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `customerId` | string | yes | The Customer identifier. Note: For API Resellers, performing actions on behalf of your customers, you need to specify the Subaccount customer identifier you're operating on behalf of. | | `domain` | string | yes | Domain name whose details are to be retrieved | ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `includes` | array | no | Optional details to be included in the response | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | string | no | A client provided identifier for tracking this request. | ### Responses **200** — Request was successful Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/DomainDetailV2` **203** — Request was partially successful, but actions, contacts, and/or verifications may not be included. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/DomainDetailV2` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — The contact does not exist Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **422** — `domain` must be specified Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. ## GET /v2/customers/{customerId}/domains/{domain}/privacy/forwarding Retrieve privacy email forwarding settings showing where emails are delivered Returns the current privacy email forwarding configuration including target address and forwarding mode. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `customerId` | string | yes | The Customer identifier. Note: For API Resellers, performing actions on behalf of your customers, you need to specify the Subaccount customer identifier you're operating on behalf of. | | `domain` | string | yes | Domain name whose details are to be retrieved | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | string | no | A client provided identifier for tracking this request. | ### Responses **200** — Request was successful Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/DomainPrivacyForwarding` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — The domain does not exist Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **422** — `domain` must be specified Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. ## PATCH /v2/customers/{customerId}/domains/{domain}/privacy/forwarding Update privacy email forwarding settings to determine how emails are delivered Updates privacy email forwarding settings. Only fields included in the request are modified. Returns 202 - poll the actions endpoint for completion. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `customerId` | string | yes | The Customer identifier. Note: For API Resellers, performing actions on behalf of your customers, you need to specify the Subaccount customer identifier you're operating on behalf of. | | `domain` | string | yes | Domain name whose details are to be retrieved | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | string | no | A client provided identifier for tracking this request. | ### Request body (required) Update privacy email forwarding settings Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/DomainPrivacyForwardingUpdate` ### Responses **202** — Request Accepted. You may use GET /v2/customers/{customerId}/domains/{domain}/actions/PRIVACY_FORWARDING_UPDATE to poll status **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — The domain does not exist Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **409** — There is already a similar action processing Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **422** — Request body doesn't fulfill schema, see details in `fields` Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. ## GET /v2/customers/{customerId}/domains/forwards/{fqdn} Retrieve the forwarding information for the given fqdn Returns the forwarding configuration for the FQDN including destination URL and redirect type. Returns 404 if no forwarding rule exists. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `customerId` | string | yes | The Customer identifier. Note: For API Resellers, performing actions on behalf of your customers, you need to specify the Subaccount customer identifier you're operating on behalf of. | | `fqdn` | string | yes | The fully qualified domain name whose forwarding details are to be retrieved. | ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `includeSubs` | boolean | no | Optionally include all sub domains if the fqdn specified is a domain and not a sub domain. | ### Responses **200** — Request was successful Content-Type: `application/json` Schema: - array - items: **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — Resource not found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **422** — A valid `fqdn` must be specified Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. ## POST /v2/customers/{customerId}/domains/forwards/{fqdn} Create a new forwarding configuration for the given FQDN Creates or replaces the forwarding configuration for the FQDN. Idempotent - replaying the same request produces the same rule. Returns 204 No Content. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `customerId` | string | yes | The Customer identifier. Note: For API Resellers, performing actions on behalf of your customers, you need to specify the Subaccount you're operating on behalf of; otherwise use your own customer id. | | `fqdn` | string | yes | The fully qualified domain name whose forwarding details are to be modified. | ### Request body (required) Domain forwarding rule to create for the specified fqdn Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/DomainForwardingCreate` ### Responses **204** — Request was successful **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — Resource not found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **409** — Provided `fqdn` already has forwarding setup Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **422** — Request body doesn't fulfill schema, see details in `fields` Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. ## DELETE /v2/customers/{customerId}/domains/forwards/{fqdn} Submit a forwarding cancellation request for the given fqdn Removes the forwarding configuration for the FQDN. Returns 204 No Content. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `customerId` | string | yes | The Customer identifier. Note: For API Resellers, performing actions on behalf of your customers, you need to specify the Subaccount customer identifier you're operating on behalf of. | | `fqdn` | string | yes | The fully qualified domain name whose forwarding details are to be deleted. | ### Responses **204** — Request was successful **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — Resource not found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **409** — The domain status does not allow performing the operation Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **422** — A valid `fqdn` must be specified Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. ## PUT /v2/customers/{customerId}/domains/forwards/{fqdn} Modify the forwarding information for the given fqdn Updates the forwarding configuration for the FQDN. Only fields included in the request are modified. Returns 204 No Content. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `customerId` | string | yes | The Customer identifier. Note: For API Resellers, performing actions on behalf of your customers, you need to specify the Subaccount customer identifier you're operating on behalf of. | | `fqdn` | string | yes | The fully qualified domain name whose forwarding details are to be modified. | ### Request body (required) Domain forwarding rule to create or replace on the fqdn Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/DomainForwardingCreate` ### Responses **204** — Request was successful **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — Resource not found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **409** — The domain status does not allow performing the operation Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **422** — Request body doesn't fulfill schema, see details in `fields` Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # Register Domains (https://developer.godaddy.com/en/docs/references/rest/domains/v2/register-domains) --- title: Register Domains description: >- Register new domains, retrieve registration schemas by TLD, and validate registration requests. full: true --- ## POST /v2/customers/{customerId}/domains/register Purchase and register the specified Domain Registers the specified domain. Requires a consent object with TLD agreement keys from the schema endpoint. Charges the account's billing method. Returns 202 - poll GET .../actions/REGISTER until the action reaches a terminal state. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `customerId` | string | yes | The Customer identifier. Note: For API Resellers, performing actions on behalf of your customers, you need to specify the Subaccount customer identifier you're operating on behalf of. | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | string | no | A client provided identifier for tracking this request. | ### Responses **202** — Request Accepted. You may use GET /v2/customers/{customerId}/domains/{domain}/actions/REGISTER to poll status **400** — Request was malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **409** — There is already a similar action processing Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **422** — Based on restrictions declared in JSON schema returned by `./schema/{tld}` Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. ## GET /v2/customers/{customerId}/domains/register/schema/{tld} Retrieve the schema to be submitted when registering a Domain for the specified TLD Returns the JSON schema for the registration request body for the specified TLD. Fetch before registering to identify required fields and TLD-specific constraints. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `customerId` | string | yes | The Customer identifier. Note: For API Resellers, performing actions on behalf of your customers, you need to specify the Subaccount customer identifier you're operating on behalf of. | | `tld` | string | yes | The Top-Level Domain whose schema should be retrieved | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | string | no | A client provided identifier for tracking this request. | ### Responses **200** — Request was successful Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/JsonSchema` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — The tld does not exist Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **422** — `tld` must be specified Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. ## POST /v2/customers/{customerId}/domains/register/validate Validate the request body using the Domain Registration Schema for the specified TLD Validates the registration request body against the TLD schema with no side effects and no charge. Returns 204 on success. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `customerId` | string | yes | The Customer identifier. Note: For API Resellers, performing actions on behalf of your customers, you need to specify the Subaccount customer identifier you're operating on behalf of. | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | string | no | A client provided identifier for tracking this request. | ### Responses **204** — Request was successful **400** — Request was malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — The customer does not exist Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **422** — Based on restrictions declared in JSON schema returned by `./schema/{tld}` Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # Transfer Domains (https://developer.godaddy.com/en/docs/references/rest/domains/v2/transfer-domains) --- title: Transfer Domains description: >- Initiate and manage inbound and outbound domain transfers and transfer lifecycle actions. full: true --- ## POST /v2/customers/{customerId}/domains/{domain}/transfer Initiate inbound transfer Initiates an inbound domain transfer from another registrar. Requires an authcode and consent object. Returns 202 - poll GET .../actions/TRANSFER until COMPLETED, FAILED, or CANCELLED. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `customerId` | string | yes | The Customer identifier. Note: For API Resellers, performing actions on behalf of your customers, you need to specify the Subaccount customer identifier you're operating on behalf of. | | `domain` | string | yes | Domain to transfer in | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | string | no | A client provided identifier for tracking this request. | ### Responses **202** — Request Accepted. You may use GET /v2/customers/{customerId}/domains/{domain}/actions/TRANSFER to poll status **400** — Request was malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — The domain does not exist Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **409** — There is already a similar action processing Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **422** — Based on restrictions declared in JSON schema returned by `./schema/{tld}` Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. ## POST /v2/customers/{customerId}/domains/{domain}/transferInAccept Accept the inbound transfer Explicitly accepts an in-progress inbound transfer to expedite the process. Returns 202 - poll GET .../actions/TRANSFER_IN_ACCEPT until the action reaches a terminal state. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `customerId` | string | yes | The Customer identifier. Note: For API Resellers, performing actions on behalf of your customers, you need to specify the Subaccount customer identifier you're operating on behalf of. | | `domain` | string | yes | Domain to accept the transfer in for | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | string | no | A client provided identifier for tracking this request. | ### Responses **202** — Request Accepted. You may use GET /v2/customers/{customerId}/domains/{domain}/actions/TRANSFER_IN_ACCEPT to poll status **400** — Request was malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — The domain does not exist Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **409** — The domain status does not allow performing the operation Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **422** — Request body doesn't fulfill schema, see details in `fields` Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. ## POST /v2/customers/{customerId}/domains/{domain}/transferInCancel Cancel the inbound transfer Cancels an in-progress inbound transfer. Returns 202 - poll GET .../actions/TRANSFER_IN_CANCEL until the action reaches a terminal state. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `customerId` | string | yes | The Customer identifier. Note: For API Resellers, performing actions on behalf of your customers, you need to specify the Subaccount customer identifier you're operating on behalf of. | | `domain` | string | yes | Domain to cancel the transfer in for | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | string | no | A client provided identifier for tracking this request. | ### Responses **202** — Request Accepted. You may use GET /v2/customers/{customerId}/domains/{domain}/actions/TRANSFER_IN_CANCEL to poll status **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — The domain does not exist Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **409** — There is already a similar action processing Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. ## POST /v2/customers/{customerId}/domains/{domain}/transferInRestart Restart the inbound transfer from the beginning Restarts a stalled inbound transfer from the beginning. Returns 202 - poll GET .../actions/TRANSFER_IN_RESTART until the action reaches a terminal state. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `customerId` | string | yes | The Customer identifier. Note: For API Resellers, performing actions on behalf of your customers, you need to specify the Subaccount customer identifier you're operating on behalf of. | | `domain` | string | yes | Domain to restart the transfer in | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | string | no | A client provided identifier for tracking this request. | ### Responses **202** — Request Accepted. You may use GET /v2/customers/{customerId}/domains/{domain}/actions/TRANSFER_IN_RESTART to poll status **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — Resource not found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **409** — The domain status does not allow performing the operation Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. ## POST /v2/customers/{customerId}/domains/{domain}/transferInRetry Retry the inbound transfer with a new authorization code Retries a failed inbound transfer with a new authorization code. Returns 202 - poll GET .../actions/TRANSFER_IN_RETRY until the action reaches a terminal state. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `customerId` | string | yes | The Customer identifier. Note: For API Resellers, performing actions on behalf of your customers, you need to specify the Subaccount customer identifier you're operating on behalf of. | | `domain` | string | yes | Domain to retry the transfer in | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | string | no | A client provided identifier for tracking this request. | ### Responses **202** — Request Accepted. You may use GET /v2/customers/{customerId}/domains/{domain}/actions/TRANSFER_IN_RETRY to poll status **400** — Request was malformed Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — Resource not found Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **409** — The domain status does not allow performing the operation Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **422** — Request body doesn't fulfill schema, see details in `fields` Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. ## POST /v2/customers/{customerId}/domains/{domain}/transferOut Initiate an outbound transfer Initiates an outbound transfer for .uk domains. Returns 202 - poll the actions endpoint for completion. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `customerId` | string | yes | The Customer identifier. Note: For API Resellers, performing actions on behalf of your customers, you need to specify the Subaccount customer identifier you're operating on behalf of. | | `domain` | string | yes | Domain to initiate the transfer out for | ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `registrar` | string | yes | Registrar tag to push transfer to | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | string | no | A client provided identifier for tracking this request. | ### Responses **202** — Request Accepted. You may use GET /v2/customers/{customerId}/domains/{domain}/actions/TRANSFER_OUT_REQUESTED to poll status **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — The domain does not exist Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **409** — There is already a similar action processing Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **422** — Domain invalid. TLD must be .uk Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. ## POST /v2/customers/{customerId}/domains/{domain}/transferOutAccept Accept the outbound transfer Accepts a pending outbound transfer request. Returns 202 - poll GET .../actions/TRANSFER_OUT_ACCEPT until the action reaches a terminal state. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `customerId` | string | yes | The Customer identifier. Note: For API Resellers, performing actions on behalf of your customers, you need to specify the Subaccount customer identifier you're operating on behalf of. | | `domain` | string | yes | Domain to accept the transfer out for | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | string | no | A client provided identifier for tracking this request. | ### Responses **202** — Request Accepted. You may use GET /v2/customers/{customerId}/domains/{domain}/actions/TRANSFER_OUT_ACCEPT to poll status **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — The domain does not exist Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **409** — There is already a similar action processing Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. ## POST /v2/customers/{customerId}/domains/{domain}/transferOutReject Reject the outbound transfer Rejects a pending outbound transfer request, keeping the domain at GoDaddy. Returns 202 - poll GET .../actions/TRANSFER_OUT_REJECT until the action reaches a terminal state. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `customerId` | string | yes | The Customer identifier. Note: For API Resellers, performing actions on behalf of your customers, you need to specify the Subaccount customer identifier you're operating on behalf of. | | `domain` | string | yes | Domain to reject the transfer out for | ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `reason` | string | no | Transfer out reject reason | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | string | no | A client provided identifier for tracking this request. | ### Responses **202** — Request Accepted. You may use GET /v2/customers/{customerId}/domains/{domain}/actions/TRANSFER_OUT_REJECT to poll status **401** — Authentication info not sent or invalid Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated user is not allowed access Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — The domain does not exist Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **409** — There is already a similar action processing Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests received within interval Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/ErrorLimit` **500** — Internal server error Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. # Check availability of one or more specific domains (https://developer.godaddy.com/en/docs/references/rest/domains/v3/check-availability) --- title: Check availability of one or more specific domains description: Batch availability check for 1-25 domains. full: true --- Full description Batch availability check for 1-25 domains. Returns one availability result per domain in input order. Domains that cannot be checked carry an error object on that item; the overall request still returns 200. Results are indicative; the authoritative check runs at quote time. ## POST /check-availability Check availability of one or more specific domains Batch availability check for 1-25 domains. Returns one availability result per domain in input order. Domains that cannot be checked carry an error object on that item; the overall request still returns 200. Results are indicative; the authoritative check runs at quote time. ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | unknown | no | Optional client-generated request correlation identifier, propagated across services and returned in the response X-Request-Id header. | ### Request body (required) Content-Type: `application/json` ```json { "domains": [ "example.com", "example.net" ] } ``` Schema: - schema reference: `#/components/schemas/AvailabilityCheckCriteria` ### Responses **200** — Per-domain availability results in request order. Uncheckable items carry an error object. Content-Type: `application/json` ```json { "items": [ { "domain": "example.com", "available": true, "definitive": false, "inventory": "REGISTRY", "prices": [ { "term": "YEAR", "period": 1, "price": { "currencyCode": "USD", "value": 1999 }, "renewalPrice": { "currencyCode": "USD", "value": 1999 } }, { "term": "YEAR", "period": 2, "price": { "currencyCode": "USD", "value": 3098 }, "renewalPrice": { "currencyCode": "USD", "value": 4598 }, "firstTermPrice": { "currencyCode": "USD", "value": 799 } }, { "term": "YEAR", "period": 3, "price": { "currencyCode": "USD", "value": 4599 }, "renewalPrice": { "currencyCode": "USD", "value": 6897 }, "firstTermPrice": { "currencyCode": "USD", "value": 499 }, "recommended": true } ] }, { "domain": "invalid..com", "error": { "name": "MISMATCH_FORMAT", "correlationId": "9f1c2e7a-4b3d-4e8f-a1c2-3d4e5f6a7b8c", "message": "does not conform to the 'domain' format, based on pattern: /^[^.\\s]{1,63}(\\.[^.\\s]{1,63}){1,2}$/" } } ] } ``` Schema: - object - `items` (required): array — Availability results in the same order as the domains array in the request body. - items: **400** — Malformed request syntax, missing required field, or invalid field type. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **401** — Authentication credentials are missing or invalid. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **403** — Authenticated identity is not authorized to perform this operation. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **422** — Semantically invalid request — valid structure but violates a business rule, such as an ineligible contact, unsupported TLD, non-renewable domain status, or quote_mismatch (e.g. iscCode or acknowledgedFees that do not match the locked quote). Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **429** — Too many requests — rate limit exceeded. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **Security:** requires `bearerAuth`. # Create a DNS record for a zone (https://developer.godaddy.com/en/docs/references/rest/domains/v3/create-dns-record) --- title: Create a DNS record for a zone description: Creates a new DNS record in the GoDaddy-managed zone. full: true --- Full description > Creates a new DNS record in the GoDaddy-managed zone. Changes are applied synchronously; no operation polling required. ## POST /zones/{zone}/dns-records Create a DNS record for a zone Creates a new DNS record in the GoDaddy-managed zone. Changes are applied synchronously; no operation polling required. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `zone` | string | yes | The domain name in punycode A-label form (for example, example.com). For IDNs, use the punycode representation. | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | unknown | no | Optional client-generated request correlation identifier, propagated across services and returned in the response X-Request-Id header. | ### Request body (required) Content-Type: `application/json` ```json { "name": "@", "type": "A", "data": "192.0.2.1", "ttl": 3600 } ``` Schema: - schema reference: `#/components/schemas/DNSRecord` ### Responses **201** — DNS record created. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/DNSRecord` **400** — Malformed request syntax, missing required field, or invalid field type. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **401** — Authentication credentials are missing or invalid. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **403** — Authenticated identity is not authorized to perform this operation. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **404** — The requested resource was not found. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **409** — Conflict — the request cannot be completed in the current state. Used for quote lifecycle errors (quote_expired, quote_consumed), domain state conflicts such as domain_already_exists, and immutable DNS records (dns_record_not_mutable) such as GoDaddy-managed SOA and NS records. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **422** — Semantically invalid request — valid structure but violates a business rule, such as an ineligible contact, unsupported TLD, non-renewable domain status, or quote_mismatch (e.g. iscCode or acknowledgedFees that do not match the locked quote). Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **429** — Too many requests — rate limit exceeded. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **Security:** requires `bearerAuth`. # Delete a DNS record (https://developer.godaddy.com/en/docs/references/rest/domains/v3/delete-dns-record) --- title: Delete a DNS record description: Permanently removes a DNS record from the zone. full: true --- Full description Permanently removes a DNS record from the zone. The recordId must refer to an existing record in the specified zone. Changes are applied synchronously. GoDaddy-managed records (SOA, NS) are read-only and return 409 when targeted. ## DELETE /zones/{zone}/dns-records/{recordId} Delete a DNS record Permanently removes a DNS record from the zone. The recordId must refer to an existing record in the specified zone. Changes are applied synchronously. GoDaddy-managed records (SOA, NS) are read-only and return 409 when targeted. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `zone` | string | yes | The domain name in punycode A-label form (for example, example.com). For IDNs, use the punycode representation. | | `recordId` | string | yes | Server-assigned DNS record identifier within the zone. | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | unknown | no | Optional client-generated request correlation identifier, propagated across services and returned in the response X-Request-Id header. | ### Responses **204** — DNS record deleted. **400** — Malformed request syntax, missing required field, or invalid field type. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **401** — Authentication credentials are missing or invalid. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **403** — Authenticated identity is not authorized to perform this operation. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **404** — The requested resource was not found. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **409** — Conflict — the request cannot be completed in the current state. Used for quote lifecycle errors (quote_expired, quote_consumed), domain state conflicts such as domain_already_exists, and immutable DNS records (dns_record_not_mutable) such as GoDaddy-managed SOA and NS records. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **429** — Too many requests — rate limit exceeded. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **Security:** requires `bearerAuth`. # Check availability of a single domain (https://developer.godaddy.com/en/docs/references/rest/domains/v3/get-domain-availability) --- title: Check availability of a single domain description: Returns an indicative availability and pricing result for a single domain. full: true --- Full description Returns an indicative availability and pricing result for a single domain. Best-effort only; the authoritative check runs at quote time. Unavailable or uncheckable domains return 200 with an error object; request-level failures use 4xx. ## GET /check-availability Check availability of a single domain Returns an indicative availability and pricing result for a single domain. Best-effort only; the authoritative check runs at quote time. Unavailable or uncheckable domains return 200 with an error object; request-level failures use 4xx. ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `domain` | string | yes | The domain name to check, in punycode A-label form for IDNs. | | `optimizeFor` | allOf(unknown) | no | Optional. When omitted, defaults to SPEED. Availability is always re-verified authoritatively at quote time regardless of this setting. | | `iscCode` | string | no | ISC (International Shopper Code) for pricing context. When provided, prices reflect the applicable rates for this ISC. | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | unknown | no | Optional client-generated request correlation identifier, propagated across services and returned in the response X-Request-Id header. | ### Responses **200** — Availability result for the requested domain. Content-Type: `application/json` ```json { "domain": "coffee24x7x365.com", "available": true, "definitive": false, "inventory": "REGISTRY", "prices": [ { "term": "YEAR", "period": 1, "price": { "currencyCode": "USD", "value": 1199 }, "renewalPrice": { "currencyCode": "USD", "value": 2299 } }, { "term": "YEAR", "period": 2, "price": { "currencyCode": "USD", "value": 3098 }, "renewalPrice": { "currencyCode": "USD", "value": 4598 }, "firstTermPrice": { "currencyCode": "USD", "value": 799 } }, { "term": "YEAR", "period": 3, "price": { "currencyCode": "USD", "value": 4599 }, "renewalPrice": { "currencyCode": "USD", "value": 6897 }, "firstTermPrice": { "currencyCode": "USD", "value": 499 }, "recommended": true }, { "term": "YEAR", "period": 5, "price": { "currencyCode": "USD", "value": 9197 }, "renewalPrice": { "currencyCode": "USD", "value": 11495 }, "firstTermPrice": { "currencyCode": "USD", "value": 100 } } ] } ``` Schema: - schema reference: `#/components/schemas/Availability` **400** — Malformed request syntax, missing required field, or invalid field type. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **401** — Authentication credentials are missing or invalid. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **403** — Authenticated identity is not authorized to perform this operation. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **422** — Semantically invalid request — valid structure but violates a business rule, such as an ineligible contact, unsupported TLD, non-renewable domain status, or quote_mismatch (e.g. iscCode or acknowledgedFees that do not match the locked quote). Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **429** — Too many requests — rate limit exceeded. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **Security:** requires `bearerAuth`. # Get a registered domain (https://developer.godaddy.com/en/docs/references/rest/domains/v3/get-domain) --- title: Get a registered domain description: >- Returns the management view of a single registered domain owned by the authenticated account, including status, nameservers, privacy and auto-renew preferences, and expiry date. full: true --- Full description > Returns the management view of a single registered domain owned by the authenticated account, including status, nameservers, privacy and auto-renew preferences, and expiry date. ## GET /domain-names/{domain-name} Get a registered domain Returns the management view of a single registered domain owned by the authenticated account, including status, nameservers, privacy and auto-renew preferences, and expiry date. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `domain-name` | string | yes | The domain name in punycode A-label form (e.g., example.com). For IDNs, use the punycode representation. | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | unknown | no | Optional client-generated request correlation identifier, propagated across services and returned in the response X-Request-Id header. | ### Responses **200** — Domain found. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Domain` **401** — Authentication credentials are missing or invalid. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **403** — Authenticated identity is not authorized to perform this operation. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **404** — The requested resource was not found. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **429** — Too many requests — rate limit exceeded. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **Security:** requires `bearerAuth`. # Poll an async domain operation (https://developer.godaddy.com/en/docs/references/rest/domains/v3/get-operation) --- title: Poll an async domain operation description: Universal poll endpoint for all asynchronous domain mutations. full: true --- Full description Universal poll endpoint for all asynchronous domain mutations. Non-terminal responses include a Retry-After header. Terminal statuses are COMPLETED (result field present) and FAILED (error field present). Poll using the URL from the initiating 202 Location header or links\[rel=self]. ## GET /operations/{operationId} Poll an async domain operation Universal poll endpoint for all asynchronous domain mutations. Non-terminal responses include a Retry-After header. Terminal statuses are COMPLETED (result field present) and FAILED (error field present). Poll using the URL from the initiating 202 Location header or links[rel=self]. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `operationId` | unknown | yes | The server-assigned operation identifier returned in the 202 response of any async domain mutation. | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | unknown | no | Optional client-generated request correlation identifier, propagated across services and returned in the response X-Request-Id header. | ### Responses **200** — Current operation state. Content-Type: `application/json` ```json { "operationId": "9f1c2e7a-4b3d-4e8f-a1c2-3d4e5f6a7b8c", "type": "REGISTER", "domain": "example.com", "status": "EXECUTING", "createdAt": "2026-06-12T10:02:05Z", "updatedAt": "2026-06-12T10:02:07Z", "links": [ { "rel": "self", "href": "https://api.godaddy.com/v3/domains/operations/9f1c2e7a-4b3d-4e8f-a1c2-3d4e5f6a7b8c" } ] } ``` Schema: - schema reference: `#/components/schemas/DomainOperation` **401** — Authentication credentials are missing or invalid. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **403** — Authenticated identity is not authorized to perform this operation. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **404** — The requested resource was not found. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **429** — Too many requests — rate limit exceeded. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **Security:** requires `bearerAuth`. # Get a registration record (https://developer.godaddy.com/en/docs/references/rest/domains/v3/get-registration) --- title: Get a registration record description: >- Returns a single registration record by its server-assigned registrationId, including the current execution status and the domain expiry date once the registration completes. full: true --- Full description > Returns a single registration record by its server-assigned registrationId, including the current execution status and the domain expiry date once the registration completes. This is the concrete poll endpoint for registration operations; the abstract equivalent is GET /operations/\{operationId}. ## GET /registrations/{registrationId} Get a registration record Returns a single registration record by its server-assigned registrationId, including the current execution status and the domain expiry date once the registration completes. This is the concrete poll endpoint for registration operations; the abstract equivalent is GET /operations/{operationId}. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `registrationId` | unknown | yes | Server-assigned registration identifier. | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | unknown | no | Optional client-generated request correlation identifier, propagated across services and returned in the response X-Request-Id header. | ### Responses **200** — Registration record returned. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Registration` **401** — Authentication credentials are missing or invalid. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **403** — Authenticated identity is not authorized to perform this operation. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **404** — The requested resource was not found. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **429** — Too many requests — rate limit exceeded. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **Security:** requires `bearerAuth`. # Overview (https://developer.godaddy.com/en/docs/references/rest/domains/v3) --- title: Overview description: > Reference for the Domains v3 API — a quote-execute model for domain discovery, registration, and management. --- ## Overview Domains v3 introduces a **quote-execute** model built for clarity and pricing predictability: 1. **Discover** — check availability and get suggestions 2. **Quote** — lock in a price with a `quoteToken` 3. **Register** — execute the registration using that token 4. **Poll** — follow the async operation to completion All write operations return `202 Accepted` with an operation or registration ID. Poll the returned URL until status reaches `COMPLETED` or `FAILED`. v3 covers domain discovery, registration, domain reads, nameserver management, and DNS records. Renewals, transfers, contact updates, forwarding, and privacy settings remain on the [v1 API](https://developer.godaddy.com/docs/references/rest/domains/v1) and [v2 API](https://developer.godaddy.com/docs/references/rest/domains/v2). The complete OpenAPI spec for the v3 namespace is available at [/openapi/domains-v3.json](https://developer.godaddy.com/openapi/domains-v3.json) — useful for code generation, SDK tooling, and LLM context. ## Endpoint groups ## Quote-execute flow **1. Check availability** ``` GET /v3/domains/check-availability?domain=example.com ``` ```json { "domain": "example.com", "available": true, "prices": [ { "term": "YEAR", "period": 1, "price": { "currencyCode": "USD", "value": 1199 }, "renewalPrice": { "currencyCode": "USD", "value": 2299 } }, { "term": "YEAR", "period": 2, "price": { "currencyCode": "USD", "value": 3098 }, "renewalPrice": { "currencyCode": "USD", "value": 4598 }, "firstTermPrice": { "currencyCode": "USD", "value": 799 } } ] } ``` **2. Lock a price** ``` POST /v3/domains/registration-quotes ``` ```json { "domain": "example.com", "period": 1 } ``` ```json { "domain": "example.com", "available": true, "quoteToken": "qt_abc123...", "expiresAt": "2026-01-15T10:45:00.000Z", "period": 1, "price": { "currencyCode": "USD", "value": 1199 }, "requiredAgreements": [{ "agreementType": "API_DPA" }] } ``` **3. Execute the registration** ``` POST /v3/domains/registrations Idempotency-Key: ``` ```json { "quoteToken": "qt_abc123...", "domain": "example.com", "period": 1, "consent": { "agreedAt": "2026-01-15T10:30:00.000Z", "agreementTypes": ["API_DPA"] } } ``` ```json { "registrationId": "reg_xyz789...", "domain": "example.com", "status": "CONFIRMED" } ``` **4. Poll to completion** ``` GET /v3/domains/registrations/{registrationId} ``` ```json { "registrationId": "reg_xyz789...", "domain": "example.com", "status": "COMPLETED" } ``` Poll every few seconds until `status` is `COMPLETED` or `FAILED`. You can also use `GET /v3/domains/operations/{operationId}` — both endpoints resolve the same resource. ## Conventions | Convention | Detail | | -------------------- | ---------------------------------------------------------------------------- | | Base URL | `https://api.godaddy.com` | | Version prefix | `/v3/` | | Async writes | `202 Accepted` with `links[rel=self]` poll URL | | Idempotency | `Idempotency-Key` header required on registration | | Indicative vs locked | Availability and suggestions return indicative prices; quotes lock the price | | Auth | `Authorization: Bearer ${GODADDY_PAT}` | ## What v3 does not cover The following operations are not yet in v3. Use v1 or v2 instead: | Operation | Use instead | | ------------------------- | ---------------------------------------------- | | Domain renewals | [Domains v1](https://developer.godaddy.com/docs/references/rest/domains/v1) | | Domain transfers | [Domains v1](https://developer.godaddy.com/docs/references/rest/domains/v1) | | Contact updates | [Domains v1](https://developer.godaddy.com/docs/references/rest/domains/v1) | | Domain forwarding | [Domains v1](https://developer.godaddy.com/docs/references/rest/domains/v1) | | Privacy settings | [Domains v1](https://developer.godaddy.com/docs/references/rest/domains/v1) | | List owned domains | [Domains v1](https://developer.godaddy.com/docs/references/rest/domains/v1) | | Shopper-scoped operations | [Domains v2](https://developer.godaddy.com/docs/references/rest/domains/v2) | # List DNS records in a zone (https://developer.godaddy.com/en/docs/references/rest/domains/v3/list-dns-records) --- title: List DNS records in a zone description: Returns a paginated collection of DNS records for the zone. full: true --- Full description Returns a paginated collection of DNS records for the zone. Supports filtering by record type and name (combined with AND), field projection, and page-based pagination. Pass totalRequired=true to include totalItems and totalPages in the response. ## GET /zones/{zone}/dns-records List DNS records in a zone Returns a paginated collection of DNS records for the zone. Supports filtering by record type and name (combined with AND), field projection, and page-based pagination. Pass totalRequired=true to include totalItems and totalPages in the response. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `zone` | string | yes | The domain name in punycode A-label form (for example, example.com). For IDNs, use the punycode representation. | ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `page` | integer | no | One-based page number for offset-based pagination. Defaults to 1. | | `pageSize` | integer | no | Maximum number of items to return per page. | | `totalRequired` | boolean | no | When true, the response includes totalItems and totalPages for the current filter when at least one record matches. Both are omitted when the result set is empty. Defaults to false; omitting totals avoids the cost of a count query on large collections. | | `fields` | string | no | Comma-separated list of fields to include in each item of the response. Omitted fields are excluded from the payload. When absent, all fields are returned. Field names must match properties defined on the item schema for the operation; any unknown or invalid name returns 400 Bad Request. | | `type` | unknown | no | Filter results to records of this DNS type. | | `name` | string | no | Filter results to records with this host name relative to the zone. Use `@` for the zone apex. | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | unknown | no | Optional client-generated request correlation identifier, propagated across services and returned in the response X-Request-Id header. | ### Responses **200** — Paginated DNS records for the zone. Content-Type: `application/json` ```json { "items": [ { "recordId": "Aad7oqdXCms9mlJvm_m6UFYqmwjyP20H2KBmQHgttK9kGbF_TuI3knsocArQqIv5I0Kq5C0", "name": "@", "type": "A", "data": "192.0.2.1", "ttl": 3600 }, { "recordId": "ARZaSm3N9qvJemM6yBmuXIO6F_YIfqSiZcaHhHFozlDsDhdOr1njlXc09TAPJlm8dXqGttRrjRKIgiXpXVm9fms", "name": "app2", "type": "A", "data": "192.0.2.2", "ttl": 3600 } ], "totalItems": 150, "totalPages": 6, "links": [ { "rel": "self", "href": "https://api.godaddy.com/v3/domains/zones/example.com/dns-records?type=A&name=app2&page=2&pageSize=25&totalRequired=true" }, { "rel": "first", "href": "https://api.godaddy.com/v3/domains/zones/example.com/dns-records?type=A&name=app2&page=1&pageSize=25&totalRequired=true" }, { "rel": "last", "href": "https://api.godaddy.com/v3/domains/zones/example.com/dns-records?type=A&name=app2&page=6&pageSize=25&totalRequired=true" }, { "rel": "next", "href": "https://api.godaddy.com/v3/domains/zones/example.com/dns-records?type=A&name=app2&page=3&pageSize=25&totalRequired=true" }, { "rel": "prev", "href": "https://api.godaddy.com/v3/domains/zones/example.com/dns-records?type=A&name=app2&page=1&pageSize=25&totalRequired=true" } ] } ``` Schema: - schema reference: `#/components/schemas/DNSRecords` **400** — Malformed request syntax, missing required field, or invalid field type. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **401** — Authentication credentials are missing or invalid. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **403** — Authenticated identity is not authorized to perform this operation. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **404** — The requested resource was not found. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **429** — Too many requests — rate limit exceeded. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **Security:** requires `bearerAuth`. # List registered domains (https://developer.godaddy.com/en/docs/references/rest/domains/v3/list-domains) --- title: List registered domains description: >- Returns a paginated collection of domain names owned by the authenticated account. full: true --- Full description Returns a paginated collection of domain names owned by the authenticated account. Supports filtering by statuses or lifecycleGroups (mutually exclusive; supplying both returns 400). An unrecognized status or lifecycle group value also returns 400. ## GET /domain-names List registered domains Returns a paginated collection of domain names owned by the authenticated account. Supports filtering by statuses or lifecycleGroups (mutually exclusive; supplying both returns 400). An unrecognized status or lifecycle group value also returns 400. ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `pageToken` | string | no | Opaque cursor from the links[rel=next or rel=prev] href of the previous page. When present, the response begins immediately after the item that produced the token. Omit to start from the beginning of the collection. | | `pageTokenDirection` | string | no | Optional token direction when `pageToken` is set; ignored otherwise. | | `pageSize` | integer | no | Maximum number of domains in the response. Defaults to 100 when omitted. Offset-based "page" parameter is not supported, only cursor-based "pageToken". | | `statuses` | array | no | Filter results to domains with one or more lifecycle statuses. Supply multiple values as a single comma-separated list, e.g. `?statuses=ACTIVE,EXPIRED`. Multiple values are combined with logical OR — returns domains matching ANY of the specified statuses. See DomainStatus for accepted values (ACTIVE, EXPIRED, PENDING_REGISTRATION, etc.). Cannot be combined with the lifecycleGroups parameter. Use this for precise filtering on specific known status values; for coarse lifecycle phases, consider lifecycleGroups. | | `lifecycleGroups` | array | no | Filter results to domains belonging to one or more status groups. Supply multiple values as a single comma-separated list, e.g. `?lifecycleGroups=REGISTERED,PENDING`. Multiple values are combined with logical OR. Cannot be combined with the statuses parameter. Use this for coarse lifecycle phases that remain stable as new statuses are added; for precise filtering, use statuses. | | `updatedAfter` | string | no | Return only domains last updated after this timestamp (exclusive). Must be a valid RFC 3339 date-time. | | `expiresBefore` | string | no | Return only domains whose registration expires before this timestamp (exclusive). Must be a valid RFC 3339 date-time. | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | unknown | no | Optional client-generated request correlation identifier, propagated across services and returned in the response X-Request-Id header. | ### Responses **200** — Paginated list of domains owned by the account. Content-Type: `application/json` ```json { "items": [ { "domain": "example.com", "status": "ACTIVE", "expiresAt": "2027-06-12T10:02:10Z", "createdAt": "2026-06-12T10:02:10Z", "autoRenew": true, "privacy": false, "transferLock": true, "nameServers": [ "ns01.domaincontrol.com", "ns02.domaincontrol.com" ], "links": [ { "rel": "self", "href": "/v3/domains/domain-names/example.com" } ] }, { "domain": "mysite.net", "status": "ACTIVE", "expiresAt": "2027-08-01T00:00:00Z", "createdAt": "2025-08-01T00:00:00Z", "autoRenew": false, "privacy": true, "transferLock": true, "nameServers": [ "ns01.domaincontrol.com", "ns02.domaincontrol.com" ], "links": [ { "rel": "self", "href": "/v3/domains/domain-names/mysite.net" } ] } ], "links": [ { "rel": "self", "href": "/v3/domains/domain-names?statuses=ACTIVE&pageSize=25" }, { "rel": "next", "href": "/v3/domains/domain-names?statuses=ACTIVE&pageSize=25&pageToken=eyJkb21haW4iOiJteXNpdGUubmV0In0" } ] } ``` Schema: - schema reference: `#/components/schemas/DomainCollection` **400** — Malformed request syntax, missing required field, or invalid field type. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **401** — Authentication credentials are missing or invalid. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **403** — Authenticated identity is not authorized to perform this operation. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **422** — Semantically invalid request — valid structure but violates a business rule, such as an ineligible contact, unsupported TLD, non-renewable domain status, or quote_mismatch (e.g. iscCode or acknowledgedFees that do not match the locked quote). Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **429** — Too many requests — rate limit exceeded. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **Security:** requires `bearerAuth`. # Quote a single-domain registration (no commitment) (https://developer.godaddy.com/en/docs/references/rest/domains/v3/quote-domain-registration) --- title: Quote a single-domain registration (no commitment) description: >- Prices the registration, resolves contact settings, and returns required legal agreements alongside a single-use quoteToken (10-minute TTL). full: true --- Full description Prices the registration, resolves contact settings, and returns required legal agreements alongside a single-use quoteToken (10-minute TTL). Free and read-only; safe to call speculatively. Returns 422 with field-level detail when required contacts are missing. ## POST /registration-quotes Quote a single-domain registration (no commitment) Prices the registration, resolves contact settings, and returns required legal agreements alongside a single-use quoteToken (10-minute TTL). Free and read-only; safe to call speculatively. Returns 422 with field-level detail when required contacts are missing. ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `iscCode` | string | no | ISC (International Shopper Code) for pricing context. When provided, prices reflect the applicable rates for this ISC. | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | unknown | no | Optional client-generated request correlation identifier, propagated across services and returned in the response X-Request-Id header. | ### Request body (required) Content-Type: `application/json` ```json { "domain": "example.com" } ``` Schema: - object - `domain` (required): string — The domain name to quote, in punycode A-label form. - `period`: integer — Registration period in years. If supplied, the same value must be re-supplied on /registrations. - `profileId`: allOf(unknown & unknown) - `profile`: allOf(unknown & unknown) ### Responses **200** — Registration quote. When available is false, no quoteToken is returned; this is not an error. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/RegistrationQuote` **400** — Malformed request syntax, missing required field, or invalid field type. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **401** — Authentication credentials are missing or invalid. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **403** — Authenticated identity is not authorized to perform this operation. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **422** — Semantically invalid request — valid structure but violates a business rule, such as an ineligible contact, unsupported TLD, non-renewable domain status, or quote_mismatch (e.g. iscCode or acknowledgedFees that do not match the locked quote). Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **429** — Too many requests — rate limit exceeded. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **Security:** requires `bearerAuth`. # Register a domain (requires quoteToken) (https://developer.godaddy.com/en/docs/references/rest/domains/v3/register-domain) --- title: Register a domain (requires quoteToken) description: Executes a previously quoted domain registration. full: true --- Full description Executes a previously quoted domain registration. Irreversible once accepted; creates a charge. Requires a valid unexpired quoteToken, an Idempotency-Key header, and a consent record. Returns a Registration entity; poll links\[rel=self] until status is COMPLETED or FAILED. ## POST /registrations Register a domain (requires quoteToken) Executes a previously quoted domain registration. Irreversible once accepted; creates a charge. Requires a valid unexpired quoteToken, an Idempotency-Key header, and a consent record. Returns a Registration entity; poll links[rel=self] until status is COMPLETED or FAILED. ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `iscCode` | string | no | ISC (International Shopper Code) for pricing context. When provided, prices reflect the applicable rates for this ISC. | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | unknown | no | Optional client-generated request correlation identifier, propagated across services and returned in the response X-Request-Id header. | | `Idempotency-Key` | string | yes | Client-generated unique key (UUID recommended). Retrying a mutating request with the same Idempotency-Key returns the original response without creating a duplicate side effect. Required on all execute endpoints. | ### Request body (required) Content-Type: `application/json` ```json { "domain": "example.com", "period": 1, "quoteToken": "7f3a2b1c-9d8e-4012-a5b6-c1d2e3f4a5b6", "consent": { "agreementTypes": [ "API_DPA" ], "agreedAt": "2026-06-12T10:02:00Z" } } ``` Schema: - schema reference: `#/components/schemas/Registration` ### Responses **202** — Registration accepted. Poll the self link for status. Content-Type: `application/json` ```json { "registrationId": "3a8f1c2d-7e6b-4f9a-b1c0-d2e3f4a5b6c7", "domain": "example.com", "period": 1, "price": { "currencyCode": "USD", "value": 1199 }, "consent": { "agreementTypes": [ "API_DPA" ], "agreedAt": "2026-06-12T10:02:00Z", "agreedBy": { "type": "DIRECT", "principal": "550e8400-e29b-41d4-a716-446655440000", "ip": "203.0.113.7" } }, "status": "CONFIRMED", "operationId": "9f1c2e7a-4b3d-4e8f-a1c2-3d4e5f6a7b8c", "createdAt": "2026-06-12T10:02:05Z", "updatedAt": "2026-06-12T10:02:05Z", "links": [ { "rel": "self", "href": "https://api.godaddy.com/v3/domains/registrations/3a8f1c2d-7e6b-4f9a-b1c0-d2e3f4a5b6c7" } ] } ``` Schema: - schema reference: `#/components/schemas/Registration` **400** — Malformed request syntax, missing required field, or invalid field type. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **401** — Authentication credentials are missing or invalid. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **403** — Authenticated identity is not authorized to perform this operation. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **409** — Conflict — the request cannot be completed in the current state. Used for quote lifecycle errors (quote_expired, quote_consumed), domain state conflicts such as domain_already_exists, and immutable DNS records (dns_record_not_mutable) such as GoDaddy-managed SOA and NS records. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **422** — Semantically invalid request — valid structure but violates a business rule, such as an ineligible contact, unsupported TLD, non-renewable domain status, or quote_mismatch (e.g. iscCode or acknowledgedFees that do not match the locked quote). Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **429** — Too many requests — rate limit exceeded. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **Security:** requires `bearerAuth`. # Replace a DNS record (https://developer.godaddy.com/en/docs/references/rest/domains/v3/replace-dns-record) --- title: Replace a DNS record description: Fully replaces an existing DNS record identified by recordId. full: true --- Full description Fully replaces an existing DNS record identified by recordId. All writable fields (name, type, data, ttl) must be supplied; partial updates are not supported. Changes are applied synchronously. GoDaddy-managed records (SOA, NS) are read-only and return 409 when targeted. ## PUT /zones/{zone}/dns-records/{recordId} Replace a DNS record Fully replaces an existing DNS record identified by recordId. All writable fields (name, type, data, ttl) must be supplied; partial updates are not supported. Changes are applied synchronously. GoDaddy-managed records (SOA, NS) are read-only and return 409 when targeted. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `zone` | string | yes | The domain name in punycode A-label form (for example, example.com). For IDNs, use the punycode representation. | | `recordId` | string | yes | Server-assigned DNS record identifier within the zone. | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | unknown | no | Optional client-generated request correlation identifier, propagated across services and returned in the response X-Request-Id header. | ### Request body (required) Content-Type: `application/json` ```json { "name": "@", "type": "A", "data": "192.0.2.1", "ttl": 3600 } ``` Schema: - schema reference: `#/components/schemas/DNSRecord` ### Responses **200** — DNS record replaced. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/DNSRecord` **400** — Malformed request syntax, missing required field, or invalid field type. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **401** — Authentication credentials are missing or invalid. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **403** — Authenticated identity is not authorized to perform this operation. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **404** — The requested resource was not found. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **409** — Conflict — the request cannot be completed in the current state. Used for quote lifecycle errors (quote_expired, quote_consumed), domain state conflicts such as domain_already_exists, and immutable DNS records (dns_record_not_mutable) such as GoDaddy-managed SOA and NS records. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **422** — Semantically invalid request — valid structure but violates a business rule, such as an ineligible contact, unsupported TLD, non-renewable domain status, or quote_mismatch (e.g. iscCode or acknowledgedFees that do not match the locked quote). Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **429** — Too many requests — rate limit exceeded. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **Security:** requires `bearerAuth`. # Suggest available domains for a query (https://developer.godaddy.com/en/docs/references/rest/domains/v3/suggest-domains) --- title: Suggest available domains for a query description: >- Returns available domain name suggestions for a natural-language query or keyword set. full: true --- Full description \| Returns available domain name suggestions for a natural-language query or keyword set. All results are available (available-only contract). Prices are indicative; the authoritative price and availability check is at quote time. ## GET /suggestions Suggest available domains for a query Returns available domain name suggestions for a natural-language query or keyword set. All results are available (available-only contract). Prices are indicative; the authoritative price and availability check is at quote time. ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `query` | string | no | Natural-language query or keywords describing the desired domain, e.g. "sunrise bakery". Used to generate creative and keyword-spin suggestions. | | `tlds` | array | no | Top-level domains to be included in suggestions. | | `lengthMax` | integer | no | Maximum length of second-level domain. | | `lengthMin` | integer | no | Minimum length of second-level domain. | | `pageSize` | integer | no | Maximum number of suggestions in the response. Defaults to 10 when omitted. | | `sources` | array | no | Suggestion source strategies to activate. | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | unknown | no | Optional client-generated request correlation identifier, propagated across services and returned in the response X-Request-Id header. | ### Responses **200** — Suggested available domains sorted by relevance. Content-Type: `application/json` ```json { "items": [ { "domain": "sunrisebakery.com", "inventory": "REGISTRY", "prices": [ { "term": "YEAR", "period": 1, "price": { "currencyCode": "USD", "value": 1199 }, "renewalPrice": { "currencyCode": "USD", "value": 2299 } }, { "term": "YEAR", "period": 2, "price": { "currencyCode": "USD", "value": 3098 }, "renewalPrice": { "currencyCode": "USD", "value": 4598 }, "firstTermPrice": { "currencyCode": "USD", "value": 799 }, "recommended": true } ] }, { "domain": "sunrisebakery.shop", "inventory": "REGISTRY", "prices": [ { "term": "YEAR", "period": 1, "price": { "currencyCode": "USD", "value": 299 }, "renewalPrice": { "currencyCode": "USD", "value": 599 } }, { "term": "YEAR", "period": 2, "price": { "currencyCode": "USD", "value": 798 }, "renewalPrice": { "currencyCode": "USD", "value": 1198 }, "firstTermPrice": { "currencyCode": "USD", "value": 199 }, "recommended": true } ] } ] } ``` Schema: - object - `items` (required): array — Available domain suggestions, sorted by relevance. All items are available by contract. - items: **400** — Malformed request syntax, missing required field, or invalid field type. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **401** — Authentication credentials are missing or invalid. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **403** — Authenticated identity is not authorized to perform this operation. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **429** — Too many requests — rate limit exceeded. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **Security:** requires `bearerAuth`. # Replace the nameservers for a domain (https://developer.godaddy.com/en/docs/references/rest/domains/v3/update-nameservers) --- title: Replace the nameservers for a domain description: Replaces the authoritative nameservers for the domain with the provided list. full: true --- Full description > Replaces the authoritative nameservers for the domain with the provided list. Minimum 2, maximum 13. Returns a DomainOperation; propagation to the registry is asynchronous. ## PUT /domain-names/{domain-name}/nameservers Replace the nameservers for a domain Replaces the authoritative nameservers for the domain with the provided list. Minimum 2, maximum 13. Returns a DomainOperation; propagation to the registry is asynchronous. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `domain-name` | string | yes | The domain name in punycode A-label form (e.g., example.com). For IDNs, use the punycode representation. | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | unknown | no | Optional client-generated request correlation identifier, propagated across services and returned in the response X-Request-Id header. | | `Idempotency-Key` | string | yes | Client-generated unique key (UUID recommended). Retrying a mutating request with the same Idempotency-Key returns the original response without creating a duplicate side effect. Required on all execute endpoints. | ### Request body (required) Content-Type: `application/json` ```json [ "ns1.example.com", "ns2.example.com" ] ``` Schema: - schema reference: `#/components/schemas/NameServers` ### Responses **202** — Nameserver update accepted; poll the operation for completion. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/DomainOperation` **400** — Malformed request syntax, missing required field, or invalid field type. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **401** — Authentication credentials are missing or invalid. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **403** — Authenticated identity is not authorized to perform this operation. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **404** — The requested resource was not found. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **422** — Semantically invalid request — valid structure but violates a business rule, such as an ineligible contact, unsupported TLD, non-renewable domain status, or quote_mismatch (e.g. iscCode or acknowledgedFees that do not match the locked quote). Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **429** — Too many requests — rate limit exceeded. Content-Type: `application/json` Schema: - schema reference: `#/x-ext/21ae8c5` **Security:** requires `bearerAuth`. # addAttributeValuesToSku (https://developer.godaddy.com/en/docs/references/rest/catalog/attribute/mutations/addAttributeValuesToSku) --- title: addAttributeValuesToSku description: Add Attribute Value(s) to an existing SKU. full: true --- mutation Requires `commerce.product:write`. Add Attribute Value(s) to an existing SKU. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationAddAttributeValuesToSkuInput!` **required** * `attributeValueIds` `[String!]!` **required** ## Possible returns * `SKU` `SKU` — A SKU represents a stock keeping unit (SKU) in the catalog. - `archivedAt` `DateTime` **nullable** — The timestamp of when the SKU was archived. - `attributes` `SKUAttributesConnection` **nullable** — Attributes are properties or characteristics of the SKU. For example, color or size. - `attributeValues` `SKUAttributeValuesConnection` **nullable** — Attribute values of SKU. - `backorderLimit` `Int` **nullable** — The number of backorders allowed for the SKU. If set to 0, backorders are not allowed. If set to null, backorders are allowed without limit. - `code` `String!` **non-null** — The unique code for the SKU. - `createdAt` `DateTime!` **non-null** — The timestamp of when the SKU was created. - `description` `String` **nullable** — The description of the SKU. - `disableInventoryTracking` `Boolean` **nullable** — Flag to mark whether stock should be tracked for the SKU. - `disablePriceOverrides` `Boolean` **nullable** — Flag to mark whether or not a custom price can be provided. - `disableShipping` `Boolean` **nullable** — Flag to mark whether the SKU should be shipped or not. - `eanCode` `String` **nullable** — The EAN code for the SKU. - `gtinCode` `String` **nullable** — The GTIN code for the SKU. - `htmlDescription` `String` **nullable** — HTML description for the SKU. Will be used to display rich text content to customers. - `id` `ID!` **non-null** — The globally-unique ID of the SKU. - `inventoryAdjustments` `SKUInventoryAdjustmentsConnection` **nullable** — An immutable entity that represents a change in state of a quantity of SKU at a particular time and location. Each adjustment will either have a positive, negative, or neutral impact on the count of available SKUs in a location. - `inventoryCounts` `SKUInventoryCountsConnection` **nullable** — The quantity of a SKU in a specific state at a particular time and location. - `isbnCode` `String` **nullable** — The ISBN code for the SKU. - `label` `String` **nullable** — The display label of the SKU. - `locations` `SKULocationsConnection` **nullable** — The locations where the SKU is available. - `mediaObjects` `SKUMediaObjectsConnection` **nullable** — Media stored under this SKU. - `metafields` `SKUMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique name for the SKU. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `prices` `SKUPricesConnection` **nullable** — These are all the prices the SKU can be sold at. The price can be different based the channel where it is listed or if there is a promotion running. - `references` `SKUReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skuGroup` `SKUGroup` **nullable** — A SKU group is a grouping of related SKUs. It provides information about all the SKUs that are sold together on storefronts or devices. - `status` `String` **nullable** — The status of the SKU, one of `DRAFT`, `ACTIVE`, `ARCHIVED`. - `unitCost` `SimpleMoney` **nullable** — The cost of the SKU per unit. This is a money object that includes the value and currency code. - `unitOfWeight` `String` **nullable** — The unit of weight, one of `KG`, `GR`, `LB`, `OZ`. - `upcCode` `String` **nullable** — The UPC code for the SKU. - `updatedAt` `DateTime!` **non-null** — The timestamp of when the SKU was updated. - `weight` `Float` **nullable** — The weight of the SKU. - `cost` `Int` **nullable** deprecated — DEPRECATED. Use unitCost instead. Deprecated: This cost field cannot specify currency code. Use `unitCost` instead. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the SKU. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. - `shortLabel` `String` **nullable** deprecated — A short label for the SKU, useful for UI with limited space. Deprecated: Use channel-specific overrides for short labels. - `SKUGroup` `SKUGroup` **nullable** deprecated — A SKU group is a grouping of related SKUs. It provides information about all the SKUs that are sold together on storefronts or devices. Deprecated: Use skuGroup instead. # addAttributesToSkuGroup (https://developer.godaddy.com/en/docs/references/rest/catalog/attribute/mutations/addAttributesToSkuGroup) --- title: addAttributesToSkuGroup description: Add Attributes to an existing SKU group. full: true --- mutation Requires `commerce.product:write`. Add Attributes to an existing SKU group. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationAddAttributesToSkuGroupInput!` **required** * `attributes` `[CreateSKUGroupAttributeInput!]!` **required** * `label` `String!` **required** * `description` `String` **optional** * `metafields` `[CreateMetafieldInput!]` **optional** * `key` `String!` **required** * `namespace` `String!` **required** * `type` `String!` **required** — Metafield value type. Live catalog validation accepts lowercase values such as `boolean`, `string`, `stringMultiLine`, `number`, `numberDecimal`, `date`, `dateTime`, `json`, `measurement`, `url`, `reference`, `money`, `list.string`, `list.number`, `list.numberDecimal`. Uppercase `STRING` is rejected. * `value` `String!` **required** * `name` `String` **optional** — Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). * `position` `Int` **optional** * `values` `[AssociateAttributeValueInput!]` **optional** * `label` `String!` **required** * `name` `String` **optional** — Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). * `position` `Int` **optional** ## Possible returns * `SKUGroup` `SKUGroup` - `activatedAt` `DateTime` **nullable** — The timestamp of when the SKU was activated. - `archivedAt` `DateTime` **nullable** — The timestamp of when the SKU was archived. - `attributes` `SKUGroupAttributesConnection` **nullable** — Attributes of SKU Group. - `channelAssociationMode` `String` **nullable** — The channel association mode for this SKU Group. Can be ALL (uses active channels registered to the store) or SELECTIVE (uses custom channel associations). - `channels` `SKUGroupChannelsConnection` **nullable** — An association to a channel that exists in the Channel API. - `compareAtPriceRange` `PriceRange` **nullable** — The compare-at price range of the SKU group, showing min and max compare-at prices of SKUs in the group. - `createdAt` `DateTime!` **non-null** — The timestamp of when the SKU was created. - `description` `String` **nullable** — The merchant defined description of the group. - `htmlDescription` `String` **nullable** — HTML description for the SKU group. Will be used to display rich text content to customers. - `id` `ID!` **non-null** — The globally-unique ID of the group. - `label` `String` **nullable** — The display label of the group. - `lists` `SKUGroupListsConnection` **nullable** — A list is a group of SKU groups that are generally organized by similar characteristics. - `mediaObjects` `SKUGroupMediaObjectsConnection` **nullable** — Media objects stored under the SKU Group. - `metafields` `SKUGroupMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique human-friendly identifier for the group. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `options` `SKUGroupOptionsConnection` **nullable** — An option is a add-on that can be added on to a SKU group. - `priceRange` `PriceRange` **nullable** — The price range of the SKU group, showing min and max prices of SKUs in the group. - `references` `SKUGroupReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skuCount` `Int` **nullable** — The count of all SKUs associated with the SKU Group. Can be filtered by status. The default statuses are ACTIVE and DRAFT. - `skus` `SKUGroupSkusConnection` **nullable** — A SKU represents a stock keeping unit (SKU) in the catalog. - `status` `String!` **non-null** — The status of the SKU Group, one of `DRAFT`, `ACTIVE`, `ARCHIVED`. - `type` `String!` **non-null** — The type of the SKU Group, typically PHYSICAL or DIGITAL, but can also be a custom type. - `updatedAt` `DateTime!` **non-null** — The timestamp of when the SKU was updated. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the SKU group. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. - `shortLabel` `String` **nullable** deprecated — A short label for the group. Can be used instead of the label on smaller screens. Deprecated: Use channel-specific overrides for short labels. - `SKUs` `SKUGroupSKUsConnection` **nullable** deprecated — A SKU represents a stock keeping unit (SKU) in the catalog. Deprecated: Use skus instead. # createAttribute (https://developer.godaddy.com/en/docs/references/rest/catalog/attribute/mutations/createAttribute) --- title: createAttribute description: Create a new attribute. full: true --- mutation Requires `commerce.product:write`. Create a new attribute. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `input` `MutationCreateAttributeInput!` **required** * `label` `String!` **required** * `skuGroupId` `ID!` **required** * `description` `String` **optional** * `htmlDescription` `String` **optional** * `HTMLDescription` `String` **optional** — Deprecated: Use htmlDescription instead. * `metafields` `[CreateMetafieldInput!]` **optional** * `key` `String!` **required** * `namespace` `String!` **required** * `type` `String!` **required** — Metafield value type. Live catalog validation accepts lowercase values such as `boolean`, `string`, `stringMultiLine`, `number`, `numberDecimal`, `date`, `dateTime`, `json`, `measurement`, `url`, `reference`, `money`, `list.string`, `list.number`, `list.numberDecimal`. Uppercase `STRING` is rejected. * `value` `String!` **required** * `name` `String` **optional** — Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). * `position` `Int` **optional** * `values` `[AssociateAttributeValueInput!]` **optional** * `label` `String!` **required** * `name` `String` **optional** — Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). * `position` `Int` **optional** ## Possible returns * `Attribute` `Attribute` — A SKU is comprised of a combination of multiple attributes - `createdAt` `DateTime!` **non-null** — The creation date of the Attribute. - `description` `String` **nullable** — A description of the Attribute. - `htmlDescription` `String` **nullable** — HTML description for the Attribute. Will be used to display rich text content to customers. - `id` `ID!` **non-null** — The UUID of the Attribute. - `label` `String` **nullable** — The display label of the Attribute. E.g. 'Color', 'Size', etc. - `metafields` `AttributeMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique name of the Attribute. E.g. 'color', 'size', etc. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `position` `Int` **nullable** — The position of the attribute. - `skuGroup` `SKUGroup` **nullable** — A SKU group is a grouping of related SKUs. It provides information about all the SKUs that are sold together on storefronts or devices. - `updatedAt` `DateTime!` **non-null** — The update date of the Attribute. - `values` `AttributeValuesConnection` **nullable** — Attribute values of Attribute. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the Attribute. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. - `SKUGroup` `SKUGroup` **nullable** deprecated — A SKU group is a grouping of related SKUs. It provides information about all the SKUs that are sold together on storefronts or devices. Deprecated: Use skuGroup instead. # createAttributeValue (https://developer.godaddy.com/en/docs/references/rest/catalog/attribute/mutations/createAttributeValue) --- title: createAttributeValue description: Create a new attribute value. full: true --- mutation Requires `commerce.product:write`. Create a new attribute value. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `input` `CreateAttributeValueInput!` **required** * `attributeId` `String!` **required** * `label` `String!` **required** * `metafields` `[CreateMetafieldInput!]` **optional** * `key` `String!` **required** * `namespace` `String!` **required** * `type` `String!` **required** — Metafield value type. Live catalog validation accepts lowercase values such as `boolean`, `string`, `stringMultiLine`, `number`, `numberDecimal`, `date`, `dateTime`, `json`, `measurement`, `url`, `reference`, `money`, `list.string`, `list.number`, `list.numberDecimal`. Uppercase `STRING` is rejected. * `value` `String!` **required** * `name` `String` **optional** — Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). * `position` `Int` **optional** ## Possible returns * `AttributeValue` `AttributeValue` — Value for an Attribute. - `attribute` `Attribute` **nullable** — The attribute that this value belongs to. - `createdAt` `DateTime!` **non-null** — The creation date of the Attribute Value. - `id` `ID!` **non-null** — The UUID of the Attribute Value. - `label` `String` **nullable** — The display label of the Attribute Value. E.g. 'Red', 'Blue', etc. - `metafields` `AttributeValueMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique name of the Attribute Value. E.g. 'red', 'blue', etc. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `position` `Int` **nullable** — The position of the attribute value. - `updatedAt` `DateTime!` **non-null** — The last update date of the Attribute Value. # createAttributeValues (https://developer.godaddy.com/en/docs/references/rest/catalog/attribute/mutations/createAttributeValues) --- title: createAttributeValues description: Create new attribute values. full: true --- mutation Requires `commerce.product:write`. Create new attribute values. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `input` `[CreateAttributeValueInput!]!` **required** * `attributeId` `String!` **required** * `label` `String!` **required** * `metafields` `[CreateMetafieldInput!]` **optional** * `key` `String!` **required** * `namespace` `String!` **required** * `type` `String!` **required** — Metafield value type. Live catalog validation accepts lowercase values such as `boolean`, `string`, `stringMultiLine`, `number`, `numberDecimal`, `date`, `dateTime`, `json`, `measurement`, `url`, `reference`, `money`, `list.string`, `list.number`, `list.numberDecimal`. Uppercase `STRING` is rejected. * `value` `String!` **required** * `name` `String` **optional** — Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). * `position` `Int` **optional** ## Possible returns * `AttributeValue` `[AttributeValue!]` — Value for an Attribute. - `attribute` `Attribute` **nullable** — The attribute that this value belongs to. - `createdAt` `DateTime!` **non-null** — The creation date of the Attribute Value. - `id` `ID!` **non-null** — The UUID of the Attribute Value. - `label` `String` **nullable** — The display label of the Attribute Value. E.g. 'Red', 'Blue', etc. - `metafields` `AttributeValueMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique name of the Attribute Value. E.g. 'red', 'blue', etc. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `position` `Int` **nullable** — The position of the attribute value. - `updatedAt` `DateTime!` **non-null** — The last update date of the Attribute Value. # removeAttributeValuesFromAttribute (https://developer.godaddy.com/en/docs/references/rest/catalog/attribute/mutations/removeAttributeValuesFromAttribute) --- title: removeAttributeValuesFromAttribute description: Remove Attribute Value(s) from an existing Attribute. full: true --- mutation Requires `commerce.product:write`. Remove Attribute Value(s) from an existing Attribute. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationRemoveAttributeValuesFromAttributeInput!` **required** * `attributeValueIds` `[String!]!` **required** ## Possible returns * `Attribute` `Attribute` — A SKU is comprised of a combination of multiple attributes - `createdAt` `DateTime!` **non-null** — The creation date of the Attribute. - `description` `String` **nullable** — A description of the Attribute. - `htmlDescription` `String` **nullable** — HTML description for the Attribute. Will be used to display rich text content to customers. - `id` `ID!` **non-null** — The UUID of the Attribute. - `label` `String` **nullable** — The display label of the Attribute. E.g. 'Color', 'Size', etc. - `metafields` `AttributeMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique name of the Attribute. E.g. 'color', 'size', etc. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `position` `Int` **nullable** — The position of the attribute. - `skuGroup` `SKUGroup` **nullable** — A SKU group is a grouping of related SKUs. It provides information about all the SKUs that are sold together on storefronts or devices. - `updatedAt` `DateTime!` **non-null** — The update date of the Attribute. - `values` `AttributeValuesConnection` **nullable** — Attribute values of Attribute. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the Attribute. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. - `SKUGroup` `SKUGroup` **nullable** deprecated — A SKU group is a grouping of related SKUs. It provides information about all the SKUs that are sold together on storefronts or devices. Deprecated: Use skuGroup instead. # removeAttributeValuesFromSku (https://developer.godaddy.com/en/docs/references/rest/catalog/attribute/mutations/removeAttributeValuesFromSku) --- title: removeAttributeValuesFromSku description: Remove Attribute Value(s) from an existing SKU. full: true --- mutation Requires `commerce.product:write`. Remove Attribute Value(s) from an existing SKU. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationRemoveAttributeValuesFromSkuInput!` **required** * `attributeValueIds` `[String!]!` **required** ## Possible returns * `SKU` `SKU` — A SKU represents a stock keeping unit (SKU) in the catalog. - `archivedAt` `DateTime` **nullable** — The timestamp of when the SKU was archived. - `attributes` `SKUAttributesConnection` **nullable** — Attributes are properties or characteristics of the SKU. For example, color or size. - `attributeValues` `SKUAttributeValuesConnection` **nullable** — Attribute values of SKU. - `backorderLimit` `Int` **nullable** — The number of backorders allowed for the SKU. If set to 0, backorders are not allowed. If set to null, backorders are allowed without limit. - `code` `String!` **non-null** — The unique code for the SKU. - `createdAt` `DateTime!` **non-null** — The timestamp of when the SKU was created. - `description` `String` **nullable** — The description of the SKU. - `disableInventoryTracking` `Boolean` **nullable** — Flag to mark whether stock should be tracked for the SKU. - `disablePriceOverrides` `Boolean` **nullable** — Flag to mark whether or not a custom price can be provided. - `disableShipping` `Boolean` **nullable** — Flag to mark whether the SKU should be shipped or not. - `eanCode` `String` **nullable** — The EAN code for the SKU. - `gtinCode` `String` **nullable** — The GTIN code for the SKU. - `htmlDescription` `String` **nullable** — HTML description for the SKU. Will be used to display rich text content to customers. - `id` `ID!` **non-null** — The globally-unique ID of the SKU. - `inventoryAdjustments` `SKUInventoryAdjustmentsConnection` **nullable** — An immutable entity that represents a change in state of a quantity of SKU at a particular time and location. Each adjustment will either have a positive, negative, or neutral impact on the count of available SKUs in a location. - `inventoryCounts` `SKUInventoryCountsConnection` **nullable** — The quantity of a SKU in a specific state at a particular time and location. - `isbnCode` `String` **nullable** — The ISBN code for the SKU. - `label` `String` **nullable** — The display label of the SKU. - `locations` `SKULocationsConnection` **nullable** — The locations where the SKU is available. - `mediaObjects` `SKUMediaObjectsConnection` **nullable** — Media stored under this SKU. - `metafields` `SKUMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique name for the SKU. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `prices` `SKUPricesConnection` **nullable** — These are all the prices the SKU can be sold at. The price can be different based the channel where it is listed or if there is a promotion running. - `references` `SKUReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skuGroup` `SKUGroup` **nullable** — A SKU group is a grouping of related SKUs. It provides information about all the SKUs that are sold together on storefronts or devices. - `status` `String` **nullable** — The status of the SKU, one of `DRAFT`, `ACTIVE`, `ARCHIVED`. - `unitCost` `SimpleMoney` **nullable** — The cost of the SKU per unit. This is a money object that includes the value and currency code. - `unitOfWeight` `String` **nullable** — The unit of weight, one of `KG`, `GR`, `LB`, `OZ`. - `upcCode` `String` **nullable** — The UPC code for the SKU. - `updatedAt` `DateTime!` **non-null** — The timestamp of when the SKU was updated. - `weight` `Float` **nullable** — The weight of the SKU. - `cost` `Int` **nullable** deprecated — DEPRECATED. Use unitCost instead. Deprecated: This cost field cannot specify currency code. Use `unitCost` instead. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the SKU. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. - `shortLabel` `String` **nullable** deprecated — A short label for the SKU, useful for UI with limited space. Deprecated: Use channel-specific overrides for short labels. - `SKUGroup` `SKUGroup` **nullable** deprecated — A SKU group is a grouping of related SKUs. It provides information about all the SKUs that are sold together on storefronts or devices. Deprecated: Use skuGroup instead. # removeAttributesFromSkuGroup (https://developer.godaddy.com/en/docs/references/rest/catalog/attribute/mutations/removeAttributesFromSkuGroup) --- title: removeAttributesFromSkuGroup description: Remove Attributes from an existing SKU group. full: true --- mutation Requires `commerce.product:write`. Remove Attributes from an existing SKU group. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationRemoveAttributesFromSkuGroupInput!` **required** * `attributeIds` `[String!]!` **required** ## Possible returns * `SKUGroup` `SKUGroup` - `activatedAt` `DateTime` **nullable** — The timestamp of when the SKU was activated. - `archivedAt` `DateTime` **nullable** — The timestamp of when the SKU was archived. - `attributes` `SKUGroupAttributesConnection` **nullable** — Attributes of SKU Group. - `channelAssociationMode` `String` **nullable** — The channel association mode for this SKU Group. Can be ALL (uses active channels registered to the store) or SELECTIVE (uses custom channel associations). - `channels` `SKUGroupChannelsConnection` **nullable** — An association to a channel that exists in the Channel API. - `compareAtPriceRange` `PriceRange` **nullable** — The compare-at price range of the SKU group, showing min and max compare-at prices of SKUs in the group. - `createdAt` `DateTime!` **non-null** — The timestamp of when the SKU was created. - `description` `String` **nullable** — The merchant defined description of the group. - `htmlDescription` `String` **nullable** — HTML description for the SKU group. Will be used to display rich text content to customers. - `id` `ID!` **non-null** — The globally-unique ID of the group. - `label` `String` **nullable** — The display label of the group. - `lists` `SKUGroupListsConnection` **nullable** — A list is a group of SKU groups that are generally organized by similar characteristics. - `mediaObjects` `SKUGroupMediaObjectsConnection` **nullable** — Media objects stored under the SKU Group. - `metafields` `SKUGroupMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique human-friendly identifier for the group. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `options` `SKUGroupOptionsConnection` **nullable** — An option is a add-on that can be added on to a SKU group. - `priceRange` `PriceRange` **nullable** — The price range of the SKU group, showing min and max prices of SKUs in the group. - `references` `SKUGroupReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skuCount` `Int` **nullable** — The count of all SKUs associated with the SKU Group. Can be filtered by status. The default statuses are ACTIVE and DRAFT. - `skus` `SKUGroupSkusConnection` **nullable** — A SKU represents a stock keeping unit (SKU) in the catalog. - `status` `String!` **non-null** — The status of the SKU Group, one of `DRAFT`, `ACTIVE`, `ARCHIVED`. - `type` `String!` **non-null** — The type of the SKU Group, typically PHYSICAL or DIGITAL, but can also be a custom type. - `updatedAt` `DateTime!` **non-null** — The timestamp of when the SKU was updated. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the SKU group. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. - `shortLabel` `String` **nullable** deprecated — A short label for the group. Can be used instead of the label on smaller screens. Deprecated: Use channel-specific overrides for short labels. - `SKUs` `SKUGroupSKUsConnection` **nullable** deprecated — A SKU represents a stock keeping unit (SKU) in the catalog. Deprecated: Use skus instead. # removeMetafieldsFromAttribute (https://developer.godaddy.com/en/docs/references/rest/catalog/attribute/mutations/removeMetafieldsFromAttribute) --- title: removeMetafieldsFromAttribute description: Remove metafields from an existing Attribute. full: true --- mutation Requires `commerce.product:write`. Remove metafields from an existing Attribute. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationRemoveMetafieldsFromAttributeInput!` **required** * `metafields` `[RemoveMetafieldInput!]!` **required** * `key` `String!` **required** * `namespace` `String!` **required** ## Possible returns * `Attribute` `Attribute` — A SKU is comprised of a combination of multiple attributes - `createdAt` `DateTime!` **non-null** — The creation date of the Attribute. - `description` `String` **nullable** — A description of the Attribute. - `htmlDescription` `String` **nullable** — HTML description for the Attribute. Will be used to display rich text content to customers. - `id` `ID!` **non-null** — The UUID of the Attribute. - `label` `String` **nullable** — The display label of the Attribute. E.g. 'Color', 'Size', etc. - `metafields` `AttributeMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique name of the Attribute. E.g. 'color', 'size', etc. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `position` `Int` **nullable** — The position of the attribute. - `skuGroup` `SKUGroup` **nullable** — A SKU group is a grouping of related SKUs. It provides information about all the SKUs that are sold together on storefronts or devices. - `updatedAt` `DateTime!` **non-null** — The update date of the Attribute. - `values` `AttributeValuesConnection` **nullable** — Attribute values of Attribute. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the Attribute. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. - `SKUGroup` `SKUGroup` **nullable** deprecated — A SKU group is a grouping of related SKUs. It provides information about all the SKUs that are sold together on storefronts or devices. Deprecated: Use skuGroup instead. # removeMetafieldsFromAttributeValue (https://developer.godaddy.com/en/docs/references/rest/catalog/attribute/mutations/removeMetafieldsFromAttributeValue) --- title: removeMetafieldsFromAttributeValue description: Remove metafields from an existing Attribute Value. full: true --- mutation Requires `commerce.product:write`. Remove metafields from an existing Attribute Value. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationRemoveMetafieldsFromAttributeValueInput!` **required** * `metafields` `[RemoveMetafieldInput!]!` **required** * `key` `String!` **required** * `namespace` `String!` **required** ## Possible returns * `AttributeValue` `AttributeValue` — Value for an Attribute. - `attribute` `Attribute` **nullable** — The attribute that this value belongs to. - `createdAt` `DateTime!` **non-null** — The creation date of the Attribute Value. - `id` `ID!` **non-null** — The UUID of the Attribute Value. - `label` `String` **nullable** — The display label of the Attribute Value. E.g. 'Red', 'Blue', etc. - `metafields` `AttributeValueMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique name of the Attribute Value. E.g. 'red', 'blue', etc. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `position` `Int` **nullable** — The position of the attribute value. - `updatedAt` `DateTime!` **non-null** — The last update date of the Attribute Value. # updateAttribute (https://developer.godaddy.com/en/docs/references/rest/catalog/attribute/mutations/updateAttribute) --- title: updateAttribute description: Update an existing attribute. full: true --- mutation Requires `commerce.product:write`. Update an existing attribute. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationUpdateAttributeInput!` **required** * `description` `String` **optional** * `htmlDescription` `String` **optional** * `HTMLDescription` `String` **optional** — Deprecated: Use htmlDescription instead. * `label` `String` **optional** * `metafields` `[UpsertMetafieldInput!]` **optional** * `key` `String!` **required** * `namespace` `String!` **required** * `type` `String!` **required** * `value` `String!` **required** * `name` `String` **optional** — Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). * `position` `Int` **optional** ## Possible returns * `Attribute` `Attribute` — A SKU is comprised of a combination of multiple attributes - `createdAt` `DateTime!` **non-null** — The creation date of the Attribute. - `description` `String` **nullable** — A description of the Attribute. - `htmlDescription` `String` **nullable** — HTML description for the Attribute. Will be used to display rich text content to customers. - `id` `ID!` **non-null** — The UUID of the Attribute. - `label` `String` **nullable** — The display label of the Attribute. E.g. 'Color', 'Size', etc. - `metafields` `AttributeMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique name of the Attribute. E.g. 'color', 'size', etc. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `position` `Int` **nullable** — The position of the attribute. - `skuGroup` `SKUGroup` **nullable** — A SKU group is a grouping of related SKUs. It provides information about all the SKUs that are sold together on storefronts or devices. - `updatedAt` `DateTime!` **non-null** — The update date of the Attribute. - `values` `AttributeValuesConnection` **nullable** — Attribute values of Attribute. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the Attribute. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. - `SKUGroup` `SKUGroup` **nullable** deprecated — A SKU group is a grouping of related SKUs. It provides information about all the SKUs that are sold together on storefronts or devices. Deprecated: Use skuGroup instead. # updateAttributeValue (https://developer.godaddy.com/en/docs/references/rest/catalog/attribute/mutations/updateAttributeValue) --- title: updateAttributeValue description: Update an existing attribute value. full: true --- mutation Requires `commerce.product:write`. Update an existing attribute value. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationUpdateAttributeValueInput!` **required** * `label` `String` **optional** * `metafields` `[UpsertMetafieldInput!]` **optional** * `key` `String!` **required** * `namespace` `String!` **required** * `type` `String!` **required** * `value` `String!` **required** * `name` `String` **optional** — Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). * `position` `Int` **optional** ## Possible returns * `AttributeValue` `AttributeValue` — Value for an Attribute. - `attribute` `Attribute` **nullable** — The attribute that this value belongs to. - `createdAt` `DateTime!` **non-null** — The creation date of the Attribute Value. - `id` `ID!` **non-null** — The UUID of the Attribute Value. - `label` `String` **nullable** — The display label of the Attribute Value. E.g. 'Red', 'Blue', etc. - `metafields` `AttributeValueMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique name of the Attribute Value. E.g. 'red', 'blue', etc. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `position` `Int` **nullable** — The position of the attribute value. - `updatedAt` `DateTime!` **non-null** — The last update date of the Attribute Value. # attribute (https://developer.godaddy.com/en/docs/references/rest/catalog/attribute/queries/attribute) --- title: attribute description: Query `attribute` on the catalog subgraph (Attribute). full: true --- query Requires `commerce.product:read`. Query `attribute` on the catalog subgraph (Attribute). ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** ## Possible returns * `Attribute` `Attribute` — A SKU is comprised of a combination of multiple attributes - `createdAt` `DateTime!` **non-null** — The creation date of the Attribute. - `description` `String` **nullable** — A description of the Attribute. - `htmlDescription` `String` **nullable** — HTML description for the Attribute. Will be used to display rich text content to customers. - `id` `ID!` **non-null** — The UUID of the Attribute. - `label` `String` **nullable** — The display label of the Attribute. E.g. 'Color', 'Size', etc. - `metafields` `AttributeMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique name of the Attribute. E.g. 'color', 'size', etc. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `position` `Int` **nullable** — The position of the attribute. - `skuGroup` `SKUGroup` **nullable** — A SKU group is a grouping of related SKUs. It provides information about all the SKUs that are sold together on storefronts or devices. - `updatedAt` `DateTime!` **non-null** — The update date of the Attribute. - `values` `AttributeValuesConnection` **nullable** — Attribute values of Attribute. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the Attribute. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. - `SKUGroup` `SKUGroup` **nullable** deprecated — A SKU group is a grouping of related SKUs. It provides information about all the SKUs that are sold together on storefronts or devices. Deprecated: Use skuGroup instead. # attributeValue (https://developer.godaddy.com/en/docs/references/rest/catalog/attribute/queries/attributeValue) --- title: attributeValue description: Query `attributeValue` on the catalog subgraph (Attribute). full: true --- query Requires `commerce.product:read`. Query `attributeValue` on the catalog subgraph (Attribute). ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** ## Possible returns * `AttributeValue` `AttributeValue` — Value for an Attribute. - `attribute` `Attribute` **nullable** — The attribute that this value belongs to. - `createdAt` `DateTime!` **non-null** — The creation date of the Attribute Value. - `id` `ID!` **non-null** — The UUID of the Attribute Value. - `label` `String` **nullable** — The display label of the Attribute Value. E.g. 'Red', 'Blue', etc. - `metafields` `AttributeValueMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique name of the Attribute Value. E.g. 'red', 'blue', etc. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `position` `Int` **nullable** — The position of the attribute value. - `updatedAt` `DateTime!` **non-null** — The last update date of the Attribute Value. # attributeValues (https://developer.godaddy.com/en/docs/references/rest/catalog/attribute/queries/attributeValues) --- title: attributeValues description: Query `attributeValues` on the catalog subgraph (Attribute). full: true --- query Requires `commerce.product:read`. Query `attributeValues` on the catalog subgraph (Attribute). ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `after` `String` **optional** * `attributeId` `AttributeIdFilter` **optional** * `eq` `String` **optional** * `in` `[String!]` **optional** * `before` `String` **optional** * `createdAt` `CreatedAtFilter` **optional** * `gt` `String` **optional** * `lt` `String` **optional** * `first` `Int` **optional** * `id` `AttributeValueIdsFilter` **optional** * `in` `[String!]` **optional** * `last` `Int` **optional** * `name` `NameFilter` **optional** * `contains` `String` **optional** — Filters items where the name contains the specified string, case-insensitive. * `eq` `String` **optional** * `in` `[String!]` **optional** — Filters items where the name matches any of the specified names. * `orderBy` `AttributeValueOrderBy` **optional** * `attributeId` `OrderByDirectionEnum` **optional** * `createdAt` `OrderByDirectionEnum` **optional** * `id` `OrderByDirectionEnum` **optional** * `name` `OrderByDirectionEnum` **optional** * `position` `OrderByDirectionEnum` **optional** * `updatedAt` `OrderByDirectionEnum` **optional** * `paginationType` `PaginationType` **optional** Default: `"CURSOR"`. * `skuId` `SKUIdFilter` **optional** * `eq` `String` **optional** * `in` `[String!]` **optional** * `updatedAt` `UpdatedAtFilter` **optional** * `gt` `String` **optional** * `lt` `String` **optional** ## Possible returns * `QueryAttributeValuesConnection` `QueryAttributeValuesConnection` - `edges` `[QueryAttributeValuesConnectionEdge]` **nullable** - `pageInfo` `PageInfo!` **non-null** - `totalCount` `Int!` **non-null** # attributes (https://developer.godaddy.com/en/docs/references/rest/catalog/attribute/queries/attributes) --- title: attributes description: Query `attributes` on the catalog subgraph (Attribute). full: true --- query Requires `commerce.product:read`. Query `attributes` on the catalog subgraph (Attribute). ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `after` `String` **optional** * `before` `String` **optional** * `createdAt` `CreatedAtFilter` **optional** * `gt` `String` **optional** * `lt` `String` **optional** * `first` `Int` **optional** * `id` `AttributeIdsFilter` **optional** * `in` `[String!]` **optional** * `last` `Int` **optional** * `name` `NameFilter` **optional** * `contains` `String` **optional** — Filters items where the name contains the specified string, case-insensitive. * `eq` `String` **optional** * `in` `[String!]` **optional** — Filters items where the name matches any of the specified names. * `orderBy` `AttributeOrderBy` **optional** * `createdAt` `OrderByDirectionEnum` **optional** * `id` `OrderByDirectionEnum` **optional** * `label` `OrderByDirectionEnum` **optional** * `name` `OrderByDirectionEnum` **optional** * `position` `OrderByDirectionEnum` **optional** * `skuGroupId` `OrderByDirectionEnum` **optional** * `updatedAt` `OrderByDirectionEnum` **optional** * `paginationType` `PaginationType` **optional** Default: `"CURSOR"`. * `skuGroupId` `SKUGroupIdFilter` **optional** * `eq` `String` **optional** * `in` `[String!]` **optional** * `skuGroupStatus` `SKUGroupStatusFilter` **optional** * `eq` `String` **optional** * `in` `[String!]` **optional** * `updatedAt` `UpdatedAtFilter` **optional** * `gt` `String` **optional** * `lt` `String` **optional** ## Possible returns * `QueryAttributesConnection` `QueryAttributesConnection` - `edges` `[QueryAttributesConnectionEdge]` **nullable** - `pageInfo` `PageInfo!` **non-null** - `totalCount` `Int!` **non-null** # addSkusToLocation (https://developer.godaddy.com/en/docs/references/rest/catalog/inventory/mutations/addSkusToLocation) --- title: addSkusToLocation description: Add SKUs to an existing location. full: true --- mutation Requires `commerce.product:write`. Add SKUs to an existing location. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationAddSkusToLocationInput!` **required** * `skuIds` `[String!]!` **required** ## Possible returns * `Location` `Location` — A location represents the physical location of an inventory. - `address` `Address` **nullable** — The address of the Location. - `createdAt` `DateTime!` **non-null** — The timestamp of when the Location was created. - `id` `ID!` **non-null** — The globally-unique ID of the Location. - `inventoryAdjustments` `LocationInventoryAdjustmentsConnection` **nullable** — An immutable entity that represents a change in state of a quantity of SKU at a particular time and location. Each adjustment will either have a positive, negative, or neutral impact on the count of available SKUs in a location. - `inventoryCounts` `LocationInventoryCountsConnection` **nullable** — The quantity of a SKU in a specific state at a particular time and location. - `label` `String` **nullable** — The display name of the Location. - `metafields` `LocationMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique and human-friendly name of the Location. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `references` `LocationReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skus` `LocationSkusConnection` **nullable** — The SKUs are purchasable items in the catalog. - `status` `String!` **non-null** — The status of the location, one of `ACTIVE`, `INACTIVE`, `ARCHIVED`. - `updatedAt` `DateTime!` **non-null** — The timestamp of when the Location was updated. - `SKUs` `LocationSKUsConnection` **nullable** deprecated — The SKUs are purchasable items in the catalog. Deprecated: Use skus instead. # adjustInventory (https://developer.godaddy.com/en/docs/references/rest/catalog/inventory/mutations/adjustInventory) --- title: adjustInventory description: >- Adjust inventory by a positive or negative delta. Positive deltas stock inventory, negative deltas reduce inventory. full: true --- mutation Requires `commerce.product:write`. Adjust inventory by a positive or negative delta. Positive deltas stock inventory, negative deltas reduce inventory. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `input` `MutationAdjustInventoryInput!` **required** * `delta` `Int!` **required** * `locationId` `ID!` **required** * `skuId` `ID!` **required** * `reasonName` `String` **optional** * `references` `[CreateReferenceInput!]` **optional** * `origin` `String!` **required** * `value` `String!` **required** ## Possible returns * `InventoryAdjustment` `[InventoryAdjustment!]` — An immutable entity that represents a change in state of a quantity of SKU at a particular time and location. - `createdAt` `DateTime` **nullable** — The creation date of the inventory adjustment. - `delta` `Int` **nullable** — The change in quantity of a SKU at a location. - `id` `ID` **nullable** — The globally-unique ID of the inventory adjustment object. - `location` `Location` **nullable** — The Location associated with the Inventory Adjustment. - `metafields` `InventoryAdjustmentMetafieldsConnection` **nullable** - `occurredAt` `DateTime` **nullable** — The date when the inventory adjustment occurred. - `reason` `InventoryAdjustmentReason` **nullable** — The reason associated with this inventory adjustment. - `references` `InventoryAdjustmentReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `sku` `SKU` **nullable** — The SKU associated with the Inventory Adjustment. - `type` `String!` **non-null** — The adjustment type of the inventory being adjusted, one of `AVAILABLE`, `COMMITTED`, `BACKORDERED`. - `SKU` `SKU` **nullable** deprecated — The SKU associated with the Inventory Adjustment. Deprecated: Use sku instead. # archiveInventoryAdjustmentReason (https://developer.godaddy.com/en/docs/references/rest/catalog/inventory/mutations/archiveInventoryAdjustmentReason) --- title: archiveInventoryAdjustmentReason description: >- Archive a store-scoped inventory adjustment reason. Global reasons cannot be archived. full: true --- mutation Requires `commerce.product:write`. Archive a store-scoped inventory adjustment reason. Global reasons cannot be archived. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `input` `MutationArchiveInventoryAdjustmentReasonInput!` **required** * `id` `ID!` **required** ## Possible returns * `InventoryAdjustmentReason` `InventoryAdjustmentReason` — A reason that can be associated with an inventory adjustment to explain why it occurred. Global preset reasons are prefixed with "g-" (e.g. g-damage, g-shrinkage). Store-scoped reasons use plain kebab-case names. - `createdAt` `DateTime` **nullable** — The date the reason was created. - `id` `ID` **nullable** — The globally-unique ID of the inventory adjustment reason. - `isGlobal` `Boolean` **nullable** — Whether this is a global preset reason. Global reasons are shared across all stores and cannot be modified or archived. - `label` `String` **nullable** — The human-readable display label of the reason. - `name` `String` **nullable** — The unique kebab-case name of the reason. Global preset names are prefixed with "g-" (e.g. g-damage). Store-scoped names must not use the "g-" prefix. - `status` `String` **nullable** — The status of the reason, one of ACTIVE, ARCHIVED. - `updatedAt` `DateTime` **nullable** — The date the reason was last updated. # archiveLocation (https://developer.godaddy.com/en/docs/references/rest/catalog/inventory/mutations/archiveLocation) --- title: archiveLocation description: Archive a location. full: true --- mutation Requires `commerce.product:write`. Archive a location. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** ## Possible returns * `Location` `Location` — A location represents the physical location of an inventory. - `address` `Address` **nullable** — The address of the Location. - `createdAt` `DateTime!` **non-null** — The timestamp of when the Location was created. - `id` `ID!` **non-null** — The globally-unique ID of the Location. - `inventoryAdjustments` `LocationInventoryAdjustmentsConnection` **nullable** — An immutable entity that represents a change in state of a quantity of SKU at a particular time and location. Each adjustment will either have a positive, negative, or neutral impact on the count of available SKUs in a location. - `inventoryCounts` `LocationInventoryCountsConnection` **nullable** — The quantity of a SKU in a specific state at a particular time and location. - `label` `String` **nullable** — The display name of the Location. - `metafields` `LocationMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique and human-friendly name of the Location. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `references` `LocationReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skus` `LocationSkusConnection` **nullable** — The SKUs are purchasable items in the catalog. - `status` `String!` **non-null** — The status of the location, one of `ACTIVE`, `INACTIVE`, `ARCHIVED`. - `updatedAt` `DateTime!` **non-null** — The timestamp of when the Location was updated. - `SKUs` `LocationSKUsConnection` **nullable** deprecated — The SKUs are purchasable items in the catalog. Deprecated: Use skus instead. # commitInventory (https://developer.godaddy.com/en/docs/references/rest/catalog/inventory/mutations/commitInventory) --- title: commitInventory description: >- Commit new inventory. If there are not enough available inventory, they will be moved to backordered if allowed. full: true --- mutation Requires `commerce.product:write`. Commit new inventory. If there are not enough available inventory, they will be moved to backordered if allowed. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `input` `MutationCommitInventoryInput!` **required** * `locationId` `ID!` **required** * `quantity` `Int!` **required** * `skuId` `ID!` **required** * `allowBackorders` `Boolean` **optional** * `reasonName` `String` **optional** * `references` `[CreateReferenceInput!]` **optional** * `origin` `String!` **required** * `value` `String!` **required** ## Possible returns * `InventoryAdjustment` `[InventoryAdjustment!]` — An immutable entity that represents a change in state of a quantity of SKU at a particular time and location. - `createdAt` `DateTime` **nullable** — The creation date of the inventory adjustment. - `delta` `Int` **nullable** — The change in quantity of a SKU at a location. - `id` `ID` **nullable** — The globally-unique ID of the inventory adjustment object. - `location` `Location` **nullable** — The Location associated with the Inventory Adjustment. - `metafields` `InventoryAdjustmentMetafieldsConnection` **nullable** - `occurredAt` `DateTime` **nullable** — The date when the inventory adjustment occurred. - `reason` `InventoryAdjustmentReason` **nullable** — The reason associated with this inventory adjustment. - `references` `InventoryAdjustmentReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `sku` `SKU` **nullable** — The SKU associated with the Inventory Adjustment. - `type` `String!` **non-null** — The adjustment type of the inventory being adjusted, one of `AVAILABLE`, `COMMITTED`, `BACKORDERED`. - `SKU` `SKU` **nullable** deprecated — The SKU associated with the Inventory Adjustment. Deprecated: Use sku instead. # createInventoryAdjustment (https://developer.godaddy.com/en/docs/references/rest/catalog/inventory/mutations/createInventoryAdjustment) --- title: createInventoryAdjustment description: Create a new inventory adjustment. full: true --- mutation Requires `commerce.product:write`. Create a new inventory adjustment. Use `CreateInventoryAdjustmentInput` with string `locationId` and `skuId`. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `input` `CreateInventoryAdjustmentInput!` **required** * `delta` `Int!` **required** — The change in inventory quantity. Positive for additions, negative for removals. * `locationId` `String!` **required** * `skuId` `String!` **required** * `type` `String!` **required** — The type of inventory adjustment, one of `AVAILABLE`, `COMMITTED`, `BACKORDERED`. * `metafields` `[CreateMetafieldInput!]` **optional** * `key` `String!` **required** * `namespace` `String!` **required** * `type` `String!` **required** — Metafield value type. Live catalog validation accepts lowercase values such as `boolean`, `string`, `stringMultiLine`, `number`, `numberDecimal`, `date`, `dateTime`, `json`, `measurement`, `url`, `reference`, `money`, `list.string`, `list.number`, `list.numberDecimal`. Uppercase `STRING` is rejected. * `value` `String!` **required** * `occurredAt` `DateTime` **optional** — The date and time when the inventory adjustment occurred. * `reasonName` `String` **optional** — The name of an inventory adjustment reason to associate with this adjustment. Use the exact reason name (e.g. "g-damage" for global presets, or a store-scoped name). * `references` `[CreateReferenceInput!]` **optional** * `origin` `String!` **required** * `value` `String!` **required** ## Possible returns * `InventoryAdjustment` `InventoryAdjustment` — An immutable entity that represents a change in state of a quantity of SKU at a particular time and location. - `createdAt` `DateTime` **nullable** — The creation date of the inventory adjustment. - `delta` `Int` **nullable** — The change in quantity of a SKU at a location. - `id` `ID` **nullable** — The globally-unique ID of the inventory adjustment object. - `location` `Location` **nullable** — The Location associated with the Inventory Adjustment. - `metafields` `InventoryAdjustmentMetafieldsConnection` **nullable** - `occurredAt` `DateTime` **nullable** — The date when the inventory adjustment occurred. - `reason` `InventoryAdjustmentReason` **nullable** — The reason associated with this inventory adjustment. - `references` `InventoryAdjustmentReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `sku` `SKU` **nullable** — The SKU associated with the Inventory Adjustment. - `type` `String!` **non-null** — The adjustment type of the inventory being adjusted, one of `AVAILABLE`, `COMMITTED`, `BACKORDERED`. - `SKU` `SKU` **nullable** deprecated — The SKU associated with the Inventory Adjustment. Deprecated: Use sku instead. # createInventoryAdjustmentReason (https://developer.godaddy.com/en/docs/references/rest/catalog/inventory/mutations/createInventoryAdjustmentReason) --- title: createInventoryAdjustmentReason description: >- Create a new store-scoped inventory adjustment reason. Name must be kebab-case and must not start with "g-" (reserved for global presets). Once created, the… full: true --- mutation Requires `commerce.product:write`. Create a new store-scoped inventory adjustment reason. Name must be kebab-case and must not start with "g-" (reserved for global presets). Once created, the name is immutable. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `input` `MutationCreateInventoryAdjustmentReasonInput!` **required** * `label` `String!` **required** * `name` `String!` **required** ## Possible returns * `InventoryAdjustmentReason` `InventoryAdjustmentReason` — A reason that can be associated with an inventory adjustment to explain why it occurred. Global preset reasons are prefixed with "g-" (e.g. g-damage, g-shrinkage). Store-scoped reasons use plain kebab-case names. - `createdAt` `DateTime` **nullable** — The date the reason was created. - `id` `ID` **nullable** — The globally-unique ID of the inventory adjustment reason. - `isGlobal` `Boolean` **nullable** — Whether this is a global preset reason. Global reasons are shared across all stores and cannot be modified or archived. - `label` `String` **nullable** — The human-readable display label of the reason. - `name` `String` **nullable** — The unique kebab-case name of the reason. Global preset names are prefixed with "g-" (e.g. g-damage). Store-scoped names must not use the "g-" prefix. - `status` `String` **nullable** — The status of the reason, one of ACTIVE, ARCHIVED. - `updatedAt` `DateTime` **nullable** — The date the reason was last updated. # createInventoryAdjustments (https://developer.godaddy.com/en/docs/references/rest/catalog/inventory/mutations/createInventoryAdjustments) --- title: createInventoryAdjustments description: Create multiple inventory adjustments in a single operation. full: true --- mutation Requires `commerce.product:write`. Create multiple inventory adjustments in a single operation. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `input` `[CreateInventoryAdjustmentInput!]!` **required** * `delta` `Int!` **required** — The change in inventory quantity. Positive for additions, negative for removals. * `locationId` `String!` **required** * `skuId` `String!` **required** * `type` `String!` **required** — The type of inventory adjustment, one of `AVAILABLE`, `COMMITTED`, `BACKORDERED`. * `metafields` `[CreateMetafieldInput!]` **optional** * `key` `String!` **required** * `namespace` `String!` **required** * `type` `String!` **required** — Metafield value type. Live catalog validation accepts lowercase values such as `boolean`, `string`, `stringMultiLine`, `number`, `numberDecimal`, `date`, `dateTime`, `json`, `measurement`, `url`, `reference`, `money`, `list.string`, `list.number`, `list.numberDecimal`. Uppercase `STRING` is rejected. * `value` `String!` **required** * `occurredAt` `DateTime` **optional** — The date and time when the inventory adjustment occurred. * `reasonName` `String` **optional** — The name of an inventory adjustment reason to associate with this adjustment. Use the exact reason name (e.g. "g-damage" for global presets, or a store-scoped name). * `references` `[CreateReferenceInput!]` **optional** * `origin` `String!` **required** * `value` `String!` **required** ## Possible returns * `InventoryAdjustment` `[InventoryAdjustment!]` — An immutable entity that represents a change in state of a quantity of SKU at a particular time and location. - `createdAt` `DateTime` **nullable** — The creation date of the inventory adjustment. - `delta` `Int` **nullable** — The change in quantity of a SKU at a location. - `id` `ID` **nullable** — The globally-unique ID of the inventory adjustment object. - `location` `Location` **nullable** — The Location associated with the Inventory Adjustment. - `metafields` `InventoryAdjustmentMetafieldsConnection` **nullable** - `occurredAt` `DateTime` **nullable** — The date when the inventory adjustment occurred. - `reason` `InventoryAdjustmentReason` **nullable** — The reason associated with this inventory adjustment. - `references` `InventoryAdjustmentReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `sku` `SKU` **nullable** — The SKU associated with the Inventory Adjustment. - `type` `String!` **non-null** — The adjustment type of the inventory being adjusted, one of `AVAILABLE`, `COMMITTED`, `BACKORDERED`. - `SKU` `SKU` **nullable** deprecated — The SKU associated with the Inventory Adjustment. Deprecated: Use sku instead. # createLocation (https://developer.godaddy.com/en/docs/references/rest/catalog/inventory/mutations/createLocation) --- title: createLocation description: Create a new location. full: true --- mutation Requires `commerce.product:write`. Create a new location. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `input` `MutationCreateLocationInput!` **required** * `address` `CreateAddressInput!` **required** * `addressLine1` `String!` **required** * `countryCode` `String!` **required** * `addressDetails` `AddressDetailsInput` **optional** * `addressType` `String` **optional** * `buildingName` `String` **optional** * `deliveryService` `String` **optional** * `geoCoordinates` `GeoCoordinatesInput` **optional** * `streetName` `String` **optional** * `streetNumber` `String` **optional** * `streetType` `String` **optional** * `subBuilding` `String` **optional** * `addressLine2` `String` **optional** * `addressLine3` `String` **optional** * `adminArea1` `String` **optional** * `adminArea2` `String` **optional** * `adminArea3` `String` **optional** * `adminArea4` `String` **optional** * `postalCode` `String` **optional** * `label` `String!` **required** * `metafields` `[CreateMetafieldInput!]` **optional** * `key` `String!` **required** * `namespace` `String!` **required** * `type` `String!` **required** — Metafield value type. Live catalog validation accepts lowercase values such as `boolean`, `string`, `stringMultiLine`, `number`, `numberDecimal`, `date`, `dateTime`, `json`, `measurement`, `url`, `reference`, `money`, `list.string`, `list.number`, `list.numberDecimal`. Uppercase `STRING` is rejected. * `value` `String!` **required** * `name` `String` **optional** — Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). * `references` `[CreateReferenceInput!]` **optional** * `origin` `String!` **required** * `value` `String!` **required** * `status` `String` **optional** — The status of the location, one of `ACTIVE`, `INACTIVE`, `ARCHIVED`. ## Possible returns * `Location` `Location` — A location represents the physical location of an inventory. - `address` `Address` **nullable** — The address of the Location. - `createdAt` `DateTime!` **non-null** — The timestamp of when the Location was created. - `id` `ID!` **non-null** — The globally-unique ID of the Location. - `inventoryAdjustments` `LocationInventoryAdjustmentsConnection` **nullable** — An immutable entity that represents a change in state of a quantity of SKU at a particular time and location. Each adjustment will either have a positive, negative, or neutral impact on the count of available SKUs in a location. - `inventoryCounts` `LocationInventoryCountsConnection` **nullable** — The quantity of a SKU in a specific state at a particular time and location. - `label` `String` **nullable** — The display name of the Location. - `metafields` `LocationMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique and human-friendly name of the Location. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `references` `LocationReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skus` `LocationSkusConnection` **nullable** — The SKUs are purchasable items in the catalog. - `status` `String!` **non-null** — The status of the location, one of `ACTIVE`, `INACTIVE`, `ARCHIVED`. - `updatedAt` `DateTime!` **non-null** — The timestamp of when the Location was updated. - `SKUs` `LocationSKUsConnection` **nullable** deprecated — The SKUs are purchasable items in the catalog. Deprecated: Use skus instead. # reduceInventory (https://developer.godaddy.com/en/docs/references/rest/catalog/inventory/mutations/reduceInventory) --- title: reduceInventory description: >- Reduce inventory by first reducing available, then moving committed to backordered. If insufficient inventory exists, additional available inventory is… full: true --- mutation Requires `commerce.product:write`. Reduce inventory by first reducing available, then moving committed to backordered. If insufficient inventory exists, additional available inventory is automatically added to fulfill the reduction. This mutation does not respect backorder limits. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `input` `MutationReduceInventoryInput!` **required** * `locationId` `ID!` **required** * `quantity` `Int!` **required** * `skuId` `ID!` **required** * `reasonName` `String` **optional** * `references` `[CreateReferenceInput!]` **optional** * `origin` `String!` **required** * `value` `String!` **required** ## Possible returns * `InventoryAdjustment` `[InventoryAdjustment!]` — An immutable entity that represents a change in state of a quantity of SKU at a particular time and location. - `createdAt` `DateTime` **nullable** — The creation date of the inventory adjustment. - `delta` `Int` **nullable** — The change in quantity of a SKU at a location. - `id` `ID` **nullable** — The globally-unique ID of the inventory adjustment object. - `location` `Location` **nullable** — The Location associated with the Inventory Adjustment. - `metafields` `InventoryAdjustmentMetafieldsConnection` **nullable** - `occurredAt` `DateTime` **nullable** — The date when the inventory adjustment occurred. - `reason` `InventoryAdjustmentReason` **nullable** — The reason associated with this inventory adjustment. - `references` `InventoryAdjustmentReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `sku` `SKU` **nullable** — The SKU associated with the Inventory Adjustment. - `type` `String!` **non-null** — The adjustment type of the inventory being adjusted, one of `AVAILABLE`, `COMMITTED`, `BACKORDERED`. - `SKU` `SKU` **nullable** deprecated — The SKU associated with the Inventory Adjustment. Deprecated: Use sku instead. # releaseInventory (https://developer.godaddy.com/en/docs/references/rest/catalog/inventory/mutations/releaseInventory) --- title: releaseInventory description: >- Release inventory from committed and/or backordered. Releases from committed first, then backordered. Errors if the requested quantity exceeds committed +… full: true --- mutation Requires `commerce.product:write`. Release inventory from committed and/or backordered. Releases from committed first, then backordered. Errors if the requested quantity exceeds committed + backordered. `releaseInventory` decreases COMMITTED first, then BACKORDERED. It does not increase AVAILABLE. To move units back to AVAILABLE, use `restockFromCommittedInventory`. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `input` `MutationReleaseInventoryInput!` **required** * `locationId` `ID!` **required** * `quantity` `Int!` **required** * `skuId` `ID!` **required** * `reasonName` `String` **optional** * `references` `[CreateReferenceInput!]` **optional** * `origin` `String!` **required** * `value` `String!` **required** ## Possible returns * `InventoryAdjustment` `[InventoryAdjustment!]` — An immutable entity that represents a change in state of a quantity of SKU at a particular time and location. - `createdAt` `DateTime` **nullable** — The creation date of the inventory adjustment. - `delta` `Int` **nullable** — The change in quantity of a SKU at a location. - `id` `ID` **nullable** — The globally-unique ID of the inventory adjustment object. - `location` `Location` **nullable** — The Location associated with the Inventory Adjustment. - `metafields` `InventoryAdjustmentMetafieldsConnection` **nullable** - `occurredAt` `DateTime` **nullable** — The date when the inventory adjustment occurred. - `reason` `InventoryAdjustmentReason` **nullable** — The reason associated with this inventory adjustment. - `references` `InventoryAdjustmentReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `sku` `SKU` **nullable** — The SKU associated with the Inventory Adjustment. - `type` `String!` **non-null** — The adjustment type of the inventory being adjusted, one of `AVAILABLE`, `COMMITTED`, `BACKORDERED`. - `SKU` `SKU` **nullable** deprecated — The SKU associated with the Inventory Adjustment. Deprecated: Use sku instead. # removeMetafieldsFromLocation (https://developer.godaddy.com/en/docs/references/rest/catalog/inventory/mutations/removeMetafieldsFromLocation) --- title: removeMetafieldsFromLocation description: Remove metafields from an existing Location. full: true --- mutation Requires `commerce.product:write`. Remove metafields from an existing Location. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationRemoveMetafieldsFromLocationInput!` **required** * `metafields` `[RemoveMetafieldInput!]!` **required** * `key` `String!` **required** * `namespace` `String!` **required** ## Possible returns * `Location` `Location` — A location represents the physical location of an inventory. - `address` `Address` **nullable** — The address of the Location. - `createdAt` `DateTime!` **non-null** — The timestamp of when the Location was created. - `id` `ID!` **non-null** — The globally-unique ID of the Location. - `inventoryAdjustments` `LocationInventoryAdjustmentsConnection` **nullable** — An immutable entity that represents a change in state of a quantity of SKU at a particular time and location. Each adjustment will either have a positive, negative, or neutral impact on the count of available SKUs in a location. - `inventoryCounts` `LocationInventoryCountsConnection` **nullable** — The quantity of a SKU in a specific state at a particular time and location. - `label` `String` **nullable** — The display name of the Location. - `metafields` `LocationMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique and human-friendly name of the Location. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `references` `LocationReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skus` `LocationSkusConnection` **nullable** — The SKUs are purchasable items in the catalog. - `status` `String!` **non-null** — The status of the location, one of `ACTIVE`, `INACTIVE`, `ARCHIVED`. - `updatedAt` `DateTime!` **non-null** — The timestamp of when the Location was updated. - `SKUs` `LocationSKUsConnection` **nullable** deprecated — The SKUs are purchasable items in the catalog. Deprecated: Use skus instead. # removeSkusFromLocation (https://developer.godaddy.com/en/docs/references/rest/catalog/inventory/mutations/removeSkusFromLocation) --- title: removeSkusFromLocation description: Remove SKU from an existing location. full: true --- mutation Requires `commerce.product:write`. Remove SKU from an existing location. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationRemoveSkusFromLocationInput!` **required** * `skuIds` `[String!]!` **required** ## Possible returns * `Location` `Location` — A location represents the physical location of an inventory. - `address` `Address` **nullable** — The address of the Location. - `createdAt` `DateTime!` **non-null** — The timestamp of when the Location was created. - `id` `ID!` **non-null** — The globally-unique ID of the Location. - `inventoryAdjustments` `LocationInventoryAdjustmentsConnection` **nullable** — An immutable entity that represents a change in state of a quantity of SKU at a particular time and location. Each adjustment will either have a positive, negative, or neutral impact on the count of available SKUs in a location. - `inventoryCounts` `LocationInventoryCountsConnection` **nullable** — The quantity of a SKU in a specific state at a particular time and location. - `label` `String` **nullable** — The display name of the Location. - `metafields` `LocationMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique and human-friendly name of the Location. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `references` `LocationReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skus` `LocationSkusConnection` **nullable** — The SKUs are purchasable items in the catalog. - `status` `String!` **non-null** — The status of the location, one of `ACTIVE`, `INACTIVE`, `ARCHIVED`. - `updatedAt` `DateTime!` **non-null** — The timestamp of when the Location was updated. - `SKUs` `LocationSKUsConnection` **nullable** deprecated — The SKUs are purchasable items in the catalog. Deprecated: Use skus instead. # restockFromCommittedInventory (https://developer.godaddy.com/en/docs/references/rest/catalog/inventory/mutations/restockFromCommittedInventory) --- title: restockFromCommittedInventory description: >- Restock inventory from committed. If there are not enough committed inventory, this mutation will error. full: true --- mutation Requires `commerce.product:write`. Restock inventory from committed. If there are not enough committed inventory, this mutation will error. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `input` `MutationRestockFromCommittedInventoryInput!` **required** * `locationId` `ID!` **required** * `quantity` `Int!` **required** * `skuId` `ID!` **required** * `reasonName` `String` **optional** * `references` `[CreateReferenceInput!]` **optional** * `origin` `String!` **required** * `value` `String!` **required** ## Possible returns * `InventoryAdjustment` `[InventoryAdjustment!]` — An immutable entity that represents a change in state of a quantity of SKU at a particular time and location. - `createdAt` `DateTime` **nullable** — The creation date of the inventory adjustment. - `delta` `Int` **nullable** — The change in quantity of a SKU at a location. - `id` `ID` **nullable** — The globally-unique ID of the inventory adjustment object. - `location` `Location` **nullable** — The Location associated with the Inventory Adjustment. - `metafields` `InventoryAdjustmentMetafieldsConnection` **nullable** - `occurredAt` `DateTime` **nullable** — The date when the inventory adjustment occurred. - `reason` `InventoryAdjustmentReason` **nullable** — The reason associated with this inventory adjustment. - `references` `InventoryAdjustmentReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `sku` `SKU` **nullable** — The SKU associated with the Inventory Adjustment. - `type` `String!` **non-null** — The adjustment type of the inventory being adjusted, one of `AVAILABLE`, `COMMITTED`, `BACKORDERED`. - `SKU` `SKU` **nullable** deprecated — The SKU associated with the Inventory Adjustment. Deprecated: Use sku instead. # stockInventory (https://developer.godaddy.com/en/docs/references/rest/catalog/inventory/mutations/stockInventory) --- title: stockInventory description: >- Stock new inventory. If there are backordered inventory, they will be moved to committed. It does not validate against backorder limit. Any extra inventory… full: true --- mutation Requires `commerce.product:write`. Stock new inventory. If there are backordered inventory, they will be moved to committed. It does not validate against backorder limit. Any extra inventory will be added to available. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `input` `MutationStockInventoryInput!` **required** * `locationId` `ID!` **required** * `quantity` `Int!` **required** * `skuId` `ID!` **required** * `reasonName` `String` **optional** * `references` `[CreateReferenceInput!]` **optional** * `origin` `String!` **required** * `value` `String!` **required** ## Possible returns * `InventoryAdjustment` `[InventoryAdjustment!]` — An immutable entity that represents a change in state of a quantity of SKU at a particular time and location. - `createdAt` `DateTime` **nullable** — The creation date of the inventory adjustment. - `delta` `Int` **nullable** — The change in quantity of a SKU at a location. - `id` `ID` **nullable** — The globally-unique ID of the inventory adjustment object. - `location` `Location` **nullable** — The Location associated with the Inventory Adjustment. - `metafields` `InventoryAdjustmentMetafieldsConnection` **nullable** - `occurredAt` `DateTime` **nullable** — The date when the inventory adjustment occurred. - `reason` `InventoryAdjustmentReason` **nullable** — The reason associated with this inventory adjustment. - `references` `InventoryAdjustmentReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `sku` `SKU` **nullable** — The SKU associated with the Inventory Adjustment. - `type` `String!` **non-null** — The adjustment type of the inventory being adjusted, one of `AVAILABLE`, `COMMITTED`, `BACKORDERED`. - `SKU` `SKU` **nullable** deprecated — The SKU associated with the Inventory Adjustment. Deprecated: Use sku instead. # updateInventoryAdjustmentReason (https://developer.godaddy.com/en/docs/references/rest/catalog/inventory/mutations/updateInventoryAdjustmentReason) --- title: updateInventoryAdjustmentReason description: >- Update the label of a store-scoped inventory adjustment reason. Global preset reasons cannot be updated. full: true --- mutation Requires `commerce.product:write`. Update the label of a store-scoped inventory adjustment reason. Global preset reasons cannot be updated. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `input` `MutationUpdateInventoryAdjustmentReasonInput!` **required** * `id` `ID!` **required** * `label` `String` **optional** ## Possible returns * `InventoryAdjustmentReason` `InventoryAdjustmentReason` — A reason that can be associated with an inventory adjustment to explain why it occurred. Global preset reasons are prefixed with "g-" (e.g. g-damage, g-shrinkage). Store-scoped reasons use plain kebab-case names. - `createdAt` `DateTime` **nullable** — The date the reason was created. - `id` `ID` **nullable** — The globally-unique ID of the inventory adjustment reason. - `isGlobal` `Boolean` **nullable** — Whether this is a global preset reason. Global reasons are shared across all stores and cannot be modified or archived. - `label` `String` **nullable** — The human-readable display label of the reason. - `name` `String` **nullable** — The unique kebab-case name of the reason. Global preset names are prefixed with "g-" (e.g. g-damage). Store-scoped names must not use the "g-" prefix. - `status` `String` **nullable** — The status of the reason, one of ACTIVE, ARCHIVED. - `updatedAt` `DateTime` **nullable** — The date the reason was last updated. # updateLocation (https://developer.godaddy.com/en/docs/references/rest/catalog/inventory/mutations/updateLocation) --- title: updateLocation description: Update an existing location. full: true --- mutation Requires `commerce.product:write`. Update an existing location. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationUpdateLocationInput!` **required** * `address` `UpdateAddressInput` **optional** * `addressDetails` `AddressDetailsInput` **optional** * `addressType` `String` **optional** * `buildingName` `String` **optional** * `deliveryService` `String` **optional** * `geoCoordinates` `GeoCoordinatesInput` **optional** * `streetName` `String` **optional** * `streetNumber` `String` **optional** * `streetType` `String` **optional** * `subBuilding` `String` **optional** * `addressLine1` `String` **optional** * `addressLine2` `String` **optional** * `addressLine3` `String` **optional** * `adminArea1` `String` **optional** * `adminArea2` `String` **optional** * `adminArea3` `String` **optional** * `adminArea4` `String` **optional** * `countryCode` `String` **optional** * `postalCode` `String` **optional** * `label` `String` **optional** * `metafields` `[UpsertMetafieldInput!]` **optional** * `key` `String!` **required** * `namespace` `String!` **required** * `type` `String!` **required** * `value` `String!` **required** * `name` `String` **optional** — Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). * `status` `String` **optional** — The status of the location, one of `ACTIVE`, `INACTIVE`, `ARCHIVED`. ## Possible returns * `Location` `Location` — A location represents the physical location of an inventory. - `address` `Address` **nullable** — The address of the Location. - `createdAt` `DateTime!` **non-null** — The timestamp of when the Location was created. - `id` `ID!` **non-null** — The globally-unique ID of the Location. - `inventoryAdjustments` `LocationInventoryAdjustmentsConnection` **nullable** — An immutable entity that represents a change in state of a quantity of SKU at a particular time and location. Each adjustment will either have a positive, negative, or neutral impact on the count of available SKUs in a location. - `inventoryCounts` `LocationInventoryCountsConnection` **nullable** — The quantity of a SKU in a specific state at a particular time and location. - `label` `String` **nullable** — The display name of the Location. - `metafields` `LocationMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique and human-friendly name of the Location. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `references` `LocationReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skus` `LocationSkusConnection` **nullable** — The SKUs are purchasable items in the catalog. - `status` `String!` **non-null** — The status of the location, one of `ACTIVE`, `INACTIVE`, `ARCHIVED`. - `updatedAt` `DateTime!` **non-null** — The timestamp of when the Location was updated. - `SKUs` `LocationSKUsConnection` **nullable** deprecated — The SKUs are purchasable items in the catalog. Deprecated: Use skus instead. # inventoryAdjustment (https://developer.godaddy.com/en/docs/references/rest/catalog/inventory/queries/inventoryAdjustment) --- title: inventoryAdjustment description: Query `inventoryAdjustment` on the catalog subgraph (Inventory). full: true --- query Requires `commerce.product:read`. Query `inventoryAdjustment` on the catalog subgraph (Inventory). ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** ## Possible returns * `InventoryAdjustment` `InventoryAdjustment` — An immutable entity that represents a change in state of a quantity of SKU at a particular time and location. - `createdAt` `DateTime` **nullable** — The creation date of the inventory adjustment. - `delta` `Int` **nullable** — The change in quantity of a SKU at a location. - `id` `ID` **nullable** — The globally-unique ID of the inventory adjustment object. - `location` `Location` **nullable** — The Location associated with the Inventory Adjustment. - `metafields` `InventoryAdjustmentMetafieldsConnection` **nullable** - `occurredAt` `DateTime` **nullable** — The date when the inventory adjustment occurred. - `reason` `InventoryAdjustmentReason` **nullable** — The reason associated with this inventory adjustment. - `references` `InventoryAdjustmentReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `sku` `SKU` **nullable** — The SKU associated with the Inventory Adjustment. - `type` `String!` **non-null** — The adjustment type of the inventory being adjusted, one of `AVAILABLE`, `COMMITTED`, `BACKORDERED`. - `SKU` `SKU` **nullable** deprecated — The SKU associated with the Inventory Adjustment. Deprecated: Use sku instead. # inventoryAdjustmentReasons (https://developer.godaddy.com/en/docs/references/rest/catalog/inventory/queries/inventoryAdjustmentReasons) --- title: inventoryAdjustmentReasons description: >- List inventory adjustment reasons available to the current store. Includes both store-scoped and global preset reasons. full: true --- query Requires `commerce.product:read`. List inventory adjustment reasons available to the current store. Includes both store-scoped and global preset reasons. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `after` `String` **optional** * `before` `String` **optional** * `first` `Int` **optional** * `last` `Int` **optional** * `name` `NameFilter` **optional** * `contains` `String` **optional** — Filters items where the name contains the specified string, case-insensitive. * `eq` `String` **optional** * `in` `[String!]` **optional** — Filters items where the name matches any of the specified names. * `orderBy` `InventoryAdjustmentReasonOrderBy` **optional** * `id` `OrderByDirectionEnum` **optional** * `paginationType` `PaginationType` **optional** Default: `"CURSOR"`. * `status` `InventoryAdjustmentReasonStatusFilter` **optional** * `eq` `String` **optional** * `in` `[String!]` **optional** ## Possible returns * `QueryInventoryAdjustmentReasonsConnection` `QueryInventoryAdjustmentReasonsConnection` - `edges` `[QueryInventoryAdjustmentReasonsConnectionEdge]` **nullable** - `pageInfo` `PageInfo!` **non-null** - `totalCount` `Int!` **non-null** # inventoryAdjustments (https://developer.godaddy.com/en/docs/references/rest/catalog/inventory/queries/inventoryAdjustments) --- title: inventoryAdjustments description: Query `inventoryAdjustments` on the catalog subgraph (Inventory). full: true --- query Requires `commerce.product:read`. Query `inventoryAdjustments` on the catalog subgraph (Inventory). ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `after` `String` **optional** * `before` `String` **optional** * `createdAt` `CreatedAtFilter` **optional** * `gt` `String` **optional** * `lt` `String` **optional** * `first` `Int` **optional** * `id` `InventoryAdjustmentIdsFilter` **optional** * `in` `[String!]` **optional** * `last` `Int` **optional** * `locationId` `LocationIdFilter` **optional** * `eq` `String` **optional** * `orderBy` `InventoryAdjustmentOrderBy` **optional** * `createdAt` `OrderByDirectionEnum` **optional** * `id` `OrderByDirectionEnum` **optional** * `paginationType` `PaginationType` **optional** Default: `"CURSOR"`. * `reasonName` `InventoryAdjustmentReasonNameFilter` **optional** * `eq` `String` **optional** * `in` `[String!]` **optional** * `referenceValue` `ReferenceValueFilter` **optional** * `eq` `String` **optional** * `in` `[String!]` **optional** * `skuId` `SKUIdFilter` **optional** * `eq` `String` **optional** * `in` `[String!]` **optional** * `type` `InventoryAdjustmentTypeFilter` **optional** * `eq` `String` **optional** * `in` `[String!]` **optional** ## Possible returns * `QueryInventoryAdjustmentsConnection` `QueryInventoryAdjustmentsConnection` - `edges` `[QueryInventoryAdjustmentsConnectionEdge]` **nullable** - `pageInfo` `PageInfo!` **non-null** - `totalCount` `Int!` **non-null** # inventoryCount (https://developer.godaddy.com/en/docs/references/rest/catalog/inventory/queries/inventoryCount) --- title: inventoryCount description: Query `inventoryCount` on the catalog subgraph (Inventory). full: true --- query Requires `commerce.product:read`. Query `inventoryCount` on the catalog subgraph (Inventory). ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `locationId` `String!` **required** * `skuId` `String!` **required** * `type` `String` **optional** ## Possible returns * `InventoryCount` `[InventoryCount!]` — Represents the quantity of a SKU in a specific state at a particular time and location. - `createdAt` `DateTime!` **non-null** — The timestamp of when the inventory count was created. - `id` `ID!` **non-null** — The globally-unique ID of the inventory count object. - `location` `Location` **nullable** — The Location associated with the Inventory Count. - `onHand` `Int` **nullable** — The on-hand inventory count (available + committed) for this SKU and location. - `quantity` `Int` **nullable** — The count of the inventory. - `sku` `SKU` **nullable** — The SKU associated with the Inventory Count. - `type` `String!` **non-null** — The type of inventory count, one of `AVAILABLE`, `COMMITTED`, `BACKORDERED`. - `updatedAt` `DateTime!` **non-null** — The timestamp of when the inventory count was updated. - `SKU` `SKU` **nullable** deprecated — The SKU associated with the Inventory Count. Deprecated: Use sku instead. # inventoryCounts (https://developer.godaddy.com/en/docs/references/rest/catalog/inventory/queries/inventoryCounts) --- title: inventoryCounts description: Query `inventoryCounts` on the catalog subgraph (Inventory). full: true --- query Requires `commerce.product:read`. Query `inventoryCounts` on the catalog subgraph (Inventory). ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `after` `String` **optional** * `before` `String` **optional** * `createdAt` `CreatedAtFilter` **optional** * `gt` `String` **optional** * `lt` `String` **optional** * `first` `Int` **optional** * `id` `InventoryCountIdsFilter` **optional** * `in` `[String!]` **optional** * `last` `Int` **optional** * `locationId` `LocationIdFilter` **optional** * `eq` `String` **optional** * `locationStatus` `LocationStatusFilter` **optional** * `eq` `String` **optional** * `in` `[String!]` **optional** * `orderBy` `InventoryCountOrderBy` **optional** * `createdAt` `OrderByDirectionEnum` **optional** * `id` `OrderByDirectionEnum` **optional** * `updatedAt` `OrderByDirectionEnum` **optional** * `paginationType` `PaginationType` **optional** Default: `"CURSOR"`. * `skuId` `SKUIdFilter` **optional** * `eq` `String` **optional** * `in` `[String!]` **optional** * `skuStatus` `InventoryCountSKUStatusFilter` **optional** * `eq` `String` **optional** * `in` `[String!]` **optional** * `type` `InventoryCountTypeFilter` **optional** * `eq` `String` **optional** * `in` `[String!]` **optional** * `updatedAt` `UpdatedAtFilter` **optional** * `gt` `String` **optional** * `lt` `String` **optional** ## Possible returns * `QueryInventoryCountsConnection` `QueryInventoryCountsConnection` - `edges` `[QueryInventoryCountsConnectionEdge]` **nullable** - `pageInfo` `PageInfo!` **non-null** - `totalCount` `Int!` **non-null** # location (https://developer.godaddy.com/en/docs/references/rest/catalog/inventory/queries/location) --- title: location description: Query `location` on the catalog subgraph (Inventory). full: true --- query Requires `commerce.product:read`. Query `location` on the catalog subgraph (Inventory). Examples use `00000000-0000-4000-a000-000000000000` as a dummy UUID, not a real location. Unknown UUID ids return HTTP 200 with `data.location: null` and no `errors`. Non-UUID strings can return `INTERNAL_SERVER_ERROR`. Query `locations` first and copy a real `id`. Nested `inventoryCounts { totalCount }` or `inventoryAdjustments { totalCount }` can return GraphQL errors on those fields while other `location` fields still resolve. Prefer top-level [`inventoryCounts`](https://developer.godaddy.com/docs/references/rest/catalog/inventory/queries/inventoryCounts) or omit nested `totalCount`. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** ## Possible returns * `Location` `Location` — A location represents the physical location of an inventory. - `address` `Address` **nullable** — The address of the Location. - `createdAt` `DateTime!` **non-null** — The timestamp of when the Location was created. - `id` `ID!` **non-null** — The globally-unique ID of the Location. - `inventoryAdjustments` `LocationInventoryAdjustmentsConnection` **nullable** — An immutable entity that represents a change in state of a quantity of SKU at a particular time and location. Each adjustment will either have a positive, negative, or neutral impact on the count of available SKUs in a location. - `inventoryCounts` `LocationInventoryCountsConnection` **nullable** — The quantity of a SKU in a specific state at a particular time and location. - `label` `String` **nullable** — The display name of the Location. - `metafields` `LocationMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique and human-friendly name of the Location. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `references` `LocationReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skus` `LocationSkusConnection` **nullable** — The SKUs are purchasable items in the catalog. - `status` `String!` **non-null** — The status of the location, one of `ACTIVE`, `INACTIVE`, `ARCHIVED`. - `updatedAt` `DateTime!` **non-null** — The timestamp of when the Location was updated. - `SKUs` `LocationSKUsConnection` **nullable** deprecated — The SKUs are purchasable items in the catalog. Deprecated: Use skus instead. # locations (https://developer.godaddy.com/en/docs/references/rest/catalog/inventory/queries/locations) --- title: locations description: Query `locations` on the catalog subgraph (Inventory). full: true --- query Requires `commerce.product:read`. Query `locations` on the catalog subgraph (Inventory). ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `after` `String` **optional** * `before` `String` **optional** * `createdAt` `CreatedAtFilter` **optional** * `gt` `String` **optional** * `lt` `String` **optional** * `first` `Int` **optional** * `id` `LocationIdsFilter` **optional** * `in` `[String!]` **optional** * `last` `Int` **optional** * `name` `NameFilter` **optional** * `contains` `String` **optional** — Filters items where the name contains the specified string, case-insensitive. * `eq` `String` **optional** * `in` `[String!]` **optional** — Filters items where the name matches any of the specified names. * `orderBy` `LocationOrderBy` **optional** * `createdAt` `OrderByDirectionEnum` **optional** * `id` `OrderByDirectionEnum` **optional** * `name` `OrderByDirectionEnum` **optional** * `updatedAt` `OrderByDirectionEnum` **optional** * `paginationType` `PaginationType` **optional** Default: `"CURSOR"`. * `referenceValue` `ReferenceValueFilter` **optional** * `eq` `String` **optional** * `in` `[String!]` **optional** * `skuId` `SKUIdFilter` **optional** * `eq` `String` **optional** * `in` `[String!]` **optional** * `status` `LocationStatusFilter` **optional** * `eq` `String` **optional** * `in` `[String!]` **optional** * `updatedAt` `UpdatedAtFilter` **optional** * `gt` `String` **optional** * `lt` `String` **optional** ## Possible returns * `QueryLocationsConnection` `QueryLocationsConnection` - `edges` `[QueryLocationsConnectionEdge]` **nullable** - `pageInfo` `PageInfo!` **non-null** - `totalCount` `Int!` **non-null** # addListTreeNodesToListTree (https://developer.godaddy.com/en/docs/references/rest/catalog/list/mutations/addListTreeNodesToListTree) --- title: addListTreeNodesToListTree description: Add a new node to a list tree. full: true --- mutation Requires `commerce.product:write`. Add a new node to a list tree. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationAddListTreeNodesToListTreeInput!` **required** * `listTreeNodes` `[AddListTreeNodeInput!]!` **required** * `listId` `String!` **required** * `parentNodeId` `String` **optional** * `position` `Int` **optional** * `references` `[CreateReferenceInput!]` **optional** * `origin` `String!` **required** * `value` `String!` **required** ## Possible returns * `ListTree` `ListTree` — A List tree holds the hierarchical information of a group of lists. - `activatedAt` `DateTime` **nullable** — The timestamp of when the list tree was activated. - `archivedAt` `DateTime` **nullable** — The timestamp of when the list tree was archived. - `createdAt` `DateTime` **nullable** — The creation date of the list tree. - `description` `String` **nullable** — The description of the list tree. - `htmlDescription` `String` **nullable** — HTML description for the List Tree. Will be used to display rich text content to customers. - `id` `ID` **nullable** — The globally-unique ID of the list tree. - `label` `String` **nullable** — The display label of the list tree. - `listTreeNodes` `ListTreeListTreeNodesConnection` **nullable** — List tree node is associated to a single List and a node can be a parent node to provide the hierarchy of list trees. - `metafields` `ListTreeMetafieldsConnection` **nullable** - `name` `String` **nullable** — A unique name of the list tree. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `references` `ListTreeReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `status` `String` **nullable** — The status of the list tree, one of `ACTIVE`, `ARCHIVED`, `DRAFT`. - `updatedAt` `DateTime` **nullable** — The last update date of the list tree. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the List Tree. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. # addListTreeNodesToParentListTreeNode (https://developer.godaddy.com/en/docs/references/rest/catalog/list/mutations/addListTreeNodesToParentListTreeNode) --- title: addListTreeNodesToParentListTreeNode description: Add a new node to a list tree node. full: true --- mutation Requires `commerce.product:write`. Add a new node to a list tree node. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationAddListTreeNodesToParentListTreeNodeInput!` **required** * `listTreeNodes` `[AddListTreeNodeInput!]!` **required** * `listId` `String!` **required** * `parentNodeId` `String` **optional** * `position` `Int` **optional** * `references` `[CreateReferenceInput!]` **optional** * `origin` `String!` **required** * `value` `String!` **required** ## Possible returns * `ListTreeNode` `ListTreeNode` — List tree node is associated to a single List and a node can be a parent node to provide the hierarchy of list trees. - `createdAt` `DateTime` **nullable** — The creation date of the list node. - `id` `ID` **nullable** — The globally-unique ID of the list node. - `list` `List` **nullable** — The list associated with the node. - `listTree` `ListTree` **nullable** — The List Tree associated with the node. - `listTreeNodes` `ListTreeNodeListTreeNodesConnection` **nullable** — The children nodes of the list node. - `parentListTreeNode` `ListTreeNode` **nullable** — The parent node of the list node. - `position` `Int` **nullable** — The position of the node in the list. - `references` `ListTreeNodeReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `updatedAt` `DateTime` **nullable** — The last update date of the list node. # addReferencesToListTreeNode (https://developer.godaddy.com/en/docs/references/rest/catalog/list/mutations/addReferencesToListTreeNode) --- title: addReferencesToListTreeNode description: Add references to an existing List Tree Node full: true --- mutation Requires `commerce.product:write`. Add references to an existing List Tree Node ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationAddReferencesToListTreeNodeInput!` **required** * `references` `[CreateReferenceInput!]!` **required** * `origin` `String!` **required** * `value` `String!` **required** ## Possible returns * `ListTreeNode` `ListTreeNode` — List tree node is associated to a single List and a node can be a parent node to provide the hierarchy of list trees. - `createdAt` `DateTime` **nullable** — The creation date of the list node. - `id` `ID` **nullable** — The globally-unique ID of the list node. - `list` `List` **nullable** — The list associated with the node. - `listTree` `ListTree` **nullable** — The List Tree associated with the node. - `listTreeNodes` `ListTreeNodeListTreeNodesConnection` **nullable** — The children nodes of the list node. - `parentListTreeNode` `ListTreeNode` **nullable** — The parent node of the list node. - `position` `Int` **nullable** — The position of the node in the list. - `references` `ListTreeNodeReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `updatedAt` `DateTime` **nullable** — The last update date of the list node. # archiveList (https://developer.godaddy.com/en/docs/references/rest/catalog/list/mutations/archiveList) --- title: archiveList description: Archive a list. full: true --- mutation Requires `commerce.product:write`. Archive a list. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** ## Possible returns * `List` `List` — A list is a group of SKU groups that are generally organized by similar characteristics. - `createdAt` `DateTime!` **non-null** — The date and time of when the List was created. - `description` `String` **nullable** — A single-line textual description of the List. - `htmlDescription` `String` **nullable** — HTML description for the List. Will be used to display rich text content to customers. - `id` `ID!` **non-null** — The globally-unique ID of the List. - `label` `String` **nullable** — The display label of the List. - `mediaObjects` `ListMediaObjectsConnection` **nullable** — Media can be images, videos, or files - `metafields` `ListMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique name for the List. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `references` `ListReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skuGroups` `ListSkuGroupsConnection` **nullable** — A SKU Group is a grouping of related SKUs. It provides information about all of the SKUs that are sold together on storefronts or devices. - `status` `String` **nullable** — The status of the list, one of `ACTIVE`, `DRAFT`, `ARCHIVED`. - `updatedAt` `DateTime!` **non-null** — The date and time of when the List was updated. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the List. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. - `SKUGroups` `ListSKUGroupsConnection` **nullable** deprecated — A SKU Group is a grouping of related SKUs. It provides information about all of the SKUs that are sold together on storefronts or devices. Deprecated: Use skuGroups instead. # archiveListTree (https://developer.godaddy.com/en/docs/references/rest/catalog/list/mutations/archiveListTree) --- title: archiveListTree description: Archive a list tree. full: true --- mutation Requires `commerce.product:write`. Archive a list tree. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** ## Possible returns * `ListTree` `ListTree` — A List tree holds the hierarchical information of a group of lists. - `activatedAt` `DateTime` **nullable** — The timestamp of when the list tree was activated. - `archivedAt` `DateTime` **nullable** — The timestamp of when the list tree was archived. - `createdAt` `DateTime` **nullable** — The creation date of the list tree. - `description` `String` **nullable** — The description of the list tree. - `htmlDescription` `String` **nullable** — HTML description for the List Tree. Will be used to display rich text content to customers. - `id` `ID` **nullable** — The globally-unique ID of the list tree. - `label` `String` **nullable** — The display label of the list tree. - `listTreeNodes` `ListTreeListTreeNodesConnection` **nullable** — List tree node is associated to a single List and a node can be a parent node to provide the hierarchy of list trees. - `metafields` `ListTreeMetafieldsConnection` **nullable** - `name` `String` **nullable** — A unique name of the list tree. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `references` `ListTreeReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `status` `String` **nullable** — The status of the list tree, one of `ACTIVE`, `ARCHIVED`, `DRAFT`. - `updatedAt` `DateTime` **nullable** — The last update date of the list tree. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the List Tree. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. # createList (https://developer.godaddy.com/en/docs/references/rest/catalog/list/mutations/createList) --- title: createList description: Create a new list. full: true --- mutation Requires `commerce.product:write`. Create a new list. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `input` `MutationCreateListInput!` **required** * `label` `String!` **required** * `description` `String` **optional** * `htmlDescription` `String` **optional** * `HTMLDescription` `String` **optional** — Deprecated: Use htmlDescription instead. * `mediaObjects` `[CreateMediaObjectInput!]` **optional** * `type` `String!` **required** — The type of the media, one of `IMAGE`, `VIDEO`, `AUDIO`. * `url` `String!` **required** * `label` `String` **optional** * `metafields` `[CreateMetafieldInput!]` **optional** * `key` `String!` **required** * `namespace` `String!` **required** * `type` `String!` **required** — Metafield value type. Live catalog validation accepts lowercase values such as `boolean`, `string`, `stringMultiLine`, `number`, `numberDecimal`, `date`, `dateTime`, `json`, `measurement`, `url`, `reference`, `money`, `list.string`, `list.number`, `list.numberDecimal`. Uppercase `STRING` is rejected. * `value` `String!` **required** * `name` `String` **optional** — Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). * `position` `Int` **optional** * `metafields` `[CreateMetafieldInput!]` **optional** * `key` `String!` **required** * `namespace` `String!` **required** * `type` `String!` **required** — Metafield value type. Live catalog validation accepts lowercase values such as `boolean`, `string`, `stringMultiLine`, `number`, `numberDecimal`, `date`, `dateTime`, `json`, `measurement`, `url`, `reference`, `money`, `list.string`, `list.number`, `list.numberDecimal`. Uppercase `STRING` is rejected. * `value` `String!` **required** * `name` `String` **optional** — Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). * `references` `[CreateReferenceInput!]` **optional** * `origin` `String!` **required** * `value` `String!` **required** * `status` `String` **optional** — The status of the list, one of `ACTIVE`, `DRAFT`, `ARCHIVED`. ## Possible returns * `List` `List` — A list is a group of SKU groups that are generally organized by similar characteristics. - `createdAt` `DateTime!` **non-null** — The date and time of when the List was created. - `description` `String` **nullable** — A single-line textual description of the List. - `htmlDescription` `String` **nullable** — HTML description for the List. Will be used to display rich text content to customers. - `id` `ID!` **non-null** — The globally-unique ID of the List. - `label` `String` **nullable** — The display label of the List. - `mediaObjects` `ListMediaObjectsConnection` **nullable** — Media can be images, videos, or files - `metafields` `ListMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique name for the List. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `references` `ListReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skuGroups` `ListSkuGroupsConnection` **nullable** — A SKU Group is a grouping of related SKUs. It provides information about all of the SKUs that are sold together on storefronts or devices. - `status` `String` **nullable** — The status of the list, one of `ACTIVE`, `DRAFT`, `ARCHIVED`. - `updatedAt` `DateTime!` **non-null** — The date and time of when the List was updated. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the List. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. - `SKUGroups` `ListSKUGroupsConnection` **nullable** deprecated — A SKU Group is a grouping of related SKUs. It provides information about all of the SKUs that are sold together on storefronts or devices. Deprecated: Use skuGroups instead. # createListTree (https://developer.godaddy.com/en/docs/references/rest/catalog/list/mutations/createListTree) --- title: createListTree description: Create a new list tree. full: true --- mutation Requires `commerce.product:write`. Create a new list tree. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `input` `MutationCreateListTreeInput!` **required** * `label` `String!` **required** * `description` `String` **optional** * `htmlDescription` `String` **optional** * `HTMLDescription` `String` **optional** — Deprecated: Use htmlDescription instead. * `listTreeNodes` `[CreateListTreeNodeInput!]` **optional** * `listId` `String!` **required** * `position` `Int` **optional** * `references` `[CreateReferenceInput!]` **optional** * `origin` `String!` **required** * `value` `String!` **required** * `metafields` `[CreateMetafieldInput!]` **optional** * `key` `String!` **required** * `namespace` `String!` **required** * `type` `String!` **required** — Metafield value type. Live catalog validation accepts lowercase values such as `boolean`, `string`, `stringMultiLine`, `number`, `numberDecimal`, `date`, `dateTime`, `json`, `measurement`, `url`, `reference`, `money`, `list.string`, `list.number`, `list.numberDecimal`. Uppercase `STRING` is rejected. * `value` `String!` **required** * `name` `String` **optional** — Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). * `references` `[CreateReferenceInput!]` **optional** * `origin` `String!` **required** * `value` `String!` **required** * `status` `String` **optional** — The status of the list tree, one of `ACTIVE`, `ARCHIVED`, `DRAFT`. ## Possible returns * `ListTree` `ListTree` — A List tree holds the hierarchical information of a group of lists. - `activatedAt` `DateTime` **nullable** — The timestamp of when the list tree was activated. - `archivedAt` `DateTime` **nullable** — The timestamp of when the list tree was archived. - `createdAt` `DateTime` **nullable** — The creation date of the list tree. - `description` `String` **nullable** — The description of the list tree. - `htmlDescription` `String` **nullable** — HTML description for the List Tree. Will be used to display rich text content to customers. - `id` `ID` **nullable** — The globally-unique ID of the list tree. - `label` `String` **nullable** — The display label of the list tree. - `listTreeNodes` `ListTreeListTreeNodesConnection` **nullable** — List tree node is associated to a single List and a node can be a parent node to provide the hierarchy of list trees. - `metafields` `ListTreeMetafieldsConnection` **nullable** - `name` `String` **nullable** — A unique name of the list tree. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `references` `ListTreeReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `status` `String` **nullable** — The status of the list tree, one of `ACTIVE`, `ARCHIVED`, `DRAFT`. - `updatedAt` `DateTime` **nullable** — The last update date of the list tree. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the List Tree. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. # removeListTreeNodesFromListTree (https://developer.godaddy.com/en/docs/references/rest/catalog/list/mutations/removeListTreeNodesFromListTree) --- title: removeListTreeNodesFromListTree description: Remove nodes from a list tree. full: true --- mutation Requires `commerce.product:write`. Remove nodes from a list tree. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationRemoveListTreeNodesFromListTreeInput!` **required** * `listTreeNodeIds` `[String!]!` **required** ## Possible returns * `ListTree` `ListTree` — A List tree holds the hierarchical information of a group of lists. - `activatedAt` `DateTime` **nullable** — The timestamp of when the list tree was activated. - `archivedAt` `DateTime` **nullable** — The timestamp of when the list tree was archived. - `createdAt` `DateTime` **nullable** — The creation date of the list tree. - `description` `String` **nullable** — The description of the list tree. - `htmlDescription` `String` **nullable** — HTML description for the List Tree. Will be used to display rich text content to customers. - `id` `ID` **nullable** — The globally-unique ID of the list tree. - `label` `String` **nullable** — The display label of the list tree. - `listTreeNodes` `ListTreeListTreeNodesConnection` **nullable** — List tree node is associated to a single List and a node can be a parent node to provide the hierarchy of list trees. - `metafields` `ListTreeMetafieldsConnection` **nullable** - `name` `String` **nullable** — A unique name of the list tree. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `references` `ListTreeReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `status` `String` **nullable** — The status of the list tree, one of `ACTIVE`, `ARCHIVED`, `DRAFT`. - `updatedAt` `DateTime` **nullable** — The last update date of the list tree. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the List Tree. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. # removeListTreeNodesFromParentListTreeNode (https://developer.godaddy.com/en/docs/references/rest/catalog/list/mutations/removeListTreeNodesFromParentListTreeNode) --- title: removeListTreeNodesFromParentListTreeNode description: Remove nodes from a list tree node. full: true --- mutation Requires `commerce.product:write`. Remove nodes from a list tree node. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationRemoveListTreeNodesFromParentListTreeNodeInput!` **required** * `listTreeNodeIds` `[String!]!` **required** ## Possible returns * `ListTreeNode` `ListTreeNode` — List tree node is associated to a single List and a node can be a parent node to provide the hierarchy of list trees. - `createdAt` `DateTime` **nullable** — The creation date of the list node. - `id` `ID` **nullable** — The globally-unique ID of the list node. - `list` `List` **nullable** — The list associated with the node. - `listTree` `ListTree` **nullable** — The List Tree associated with the node. - `listTreeNodes` `ListTreeNodeListTreeNodesConnection` **nullable** — The children nodes of the list node. - `parentListTreeNode` `ListTreeNode` **nullable** — The parent node of the list node. - `position` `Int` **nullable** — The position of the node in the list. - `references` `ListTreeNodeReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `updatedAt` `DateTime` **nullable** — The last update date of the list node. # removeMetafieldsFromList (https://developer.godaddy.com/en/docs/references/rest/catalog/list/mutations/removeMetafieldsFromList) --- title: removeMetafieldsFromList description: Remove metafields from an existing List. full: true --- mutation Requires `commerce.product:write`. Remove metafields from an existing List. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationRemoveMetafieldsFromListInput!` **required** * `metafields` `[RemoveMetafieldInput!]!` **required** * `key` `String!` **required** * `namespace` `String!` **required** ## Possible returns * `List` `List` — A list is a group of SKU groups that are generally organized by similar characteristics. - `createdAt` `DateTime!` **non-null** — The date and time of when the List was created. - `description` `String` **nullable** — A single-line textual description of the List. - `htmlDescription` `String` **nullable** — HTML description for the List. Will be used to display rich text content to customers. - `id` `ID!` **non-null** — The globally-unique ID of the List. - `label` `String` **nullable** — The display label of the List. - `mediaObjects` `ListMediaObjectsConnection` **nullable** — Media can be images, videos, or files - `metafields` `ListMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique name for the List. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `references` `ListReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skuGroups` `ListSkuGroupsConnection` **nullable** — A SKU Group is a grouping of related SKUs. It provides information about all of the SKUs that are sold together on storefronts or devices. - `status` `String` **nullable** — The status of the list, one of `ACTIVE`, `DRAFT`, `ARCHIVED`. - `updatedAt` `DateTime!` **non-null** — The date and time of when the List was updated. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the List. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. - `SKUGroups` `ListSKUGroupsConnection` **nullable** deprecated — A SKU Group is a grouping of related SKUs. It provides information about all of the SKUs that are sold together on storefronts or devices. Deprecated: Use skuGroups instead. # removeMetafieldsFromListTree (https://developer.godaddy.com/en/docs/references/rest/catalog/list/mutations/removeMetafieldsFromListTree) --- title: removeMetafieldsFromListTree description: Remove metafields from an existing List Tree. full: true --- mutation Requires `commerce.product:write`. Remove metafields from an existing List Tree. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationRemoveMetafieldsFromListTreeInput!` **required** * `metafields` `[RemoveMetafieldInput!]!` **required** * `key` `String!` **required** * `namespace` `String!` **required** ## Possible returns * `ListTree` `ListTree` — A List tree holds the hierarchical information of a group of lists. - `activatedAt` `DateTime` **nullable** — The timestamp of when the list tree was activated. - `archivedAt` `DateTime` **nullable** — The timestamp of when the list tree was archived. - `createdAt` `DateTime` **nullable** — The creation date of the list tree. - `description` `String` **nullable** — The description of the list tree. - `htmlDescription` `String` **nullable** — HTML description for the List Tree. Will be used to display rich text content to customers. - `id` `ID` **nullable** — The globally-unique ID of the list tree. - `label` `String` **nullable** — The display label of the list tree. - `listTreeNodes` `ListTreeListTreeNodesConnection` **nullable** — List tree node is associated to a single List and a node can be a parent node to provide the hierarchy of list trees. - `metafields` `ListTreeMetafieldsConnection` **nullable** - `name` `String` **nullable** — A unique name of the list tree. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `references` `ListTreeReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `status` `String` **nullable** — The status of the list tree, one of `ACTIVE`, `ARCHIVED`, `DRAFT`. - `updatedAt` `DateTime` **nullable** — The last update date of the list tree. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the List Tree. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. # removeReferencesFromListTreeNode (https://developer.godaddy.com/en/docs/references/rest/catalog/list/mutations/removeReferencesFromListTreeNode) --- title: removeReferencesFromListTreeNode description: Remove references from an existing List Tree Node full: true --- mutation Requires `commerce.product:write`. Remove references from an existing List Tree Node ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationRemoveReferencesFromListTreeNodeInput!` **required** * `referenceIds` `[String!]!` **required** ## Possible returns * `ListTreeNode` `ListTreeNode` — List tree node is associated to a single List and a node can be a parent node to provide the hierarchy of list trees. - `createdAt` `DateTime` **nullable** — The creation date of the list node. - `id` `ID` **nullable** — The globally-unique ID of the list node. - `list` `List` **nullable** — The list associated with the node. - `listTree` `ListTree` **nullable** — The List Tree associated with the node. - `listTreeNodes` `ListTreeNodeListTreeNodesConnection` **nullable** — The children nodes of the list node. - `parentListTreeNode` `ListTreeNode` **nullable** — The parent node of the list node. - `position` `Int` **nullable** — The position of the node in the list. - `references` `ListTreeNodeReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `updatedAt` `DateTime` **nullable** — The last update date of the list node. # updateList (https://developer.godaddy.com/en/docs/references/rest/catalog/list/mutations/updateList) --- title: updateList description: Update an existing list. full: true --- mutation Requires `commerce.product:write`. Update an existing list. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationUpdateListInput!` **required** * `description` `String` **optional** * `htmlDescription` `String` **optional** * `HTMLDescription` `String` **optional** — Deprecated: Use htmlDescription instead. * `label` `String` **optional** * `metafields` `[UpsertMetafieldInput!]` **optional** * `key` `String!` **required** * `namespace` `String!` **required** * `type` `String!` **required** * `value` `String!` **required** * `name` `String` **optional** — Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). * `status` `String` **optional** — The status of the list, one of `ACTIVE`, `DRAFT`, `ARCHIVED`. ## Possible returns * `List` `List` — A list is a group of SKU groups that are generally organized by similar characteristics. - `createdAt` `DateTime!` **non-null** — The date and time of when the List was created. - `description` `String` **nullable** — A single-line textual description of the List. - `htmlDescription` `String` **nullable** — HTML description for the List. Will be used to display rich text content to customers. - `id` `ID!` **non-null** — The globally-unique ID of the List. - `label` `String` **nullable** — The display label of the List. - `mediaObjects` `ListMediaObjectsConnection` **nullable** — Media can be images, videos, or files - `metafields` `ListMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique name for the List. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `references` `ListReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skuGroups` `ListSkuGroupsConnection` **nullable** — A SKU Group is a grouping of related SKUs. It provides information about all of the SKUs that are sold together on storefronts or devices. - `status` `String` **nullable** — The status of the list, one of `ACTIVE`, `DRAFT`, `ARCHIVED`. - `updatedAt` `DateTime!` **non-null** — The date and time of when the List was updated. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the List. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. - `SKUGroups` `ListSKUGroupsConnection` **nullable** deprecated — A SKU Group is a grouping of related SKUs. It provides information about all of the SKUs that are sold together on storefronts or devices. Deprecated: Use skuGroups instead. # updateListTree (https://developer.godaddy.com/en/docs/references/rest/catalog/list/mutations/updateListTree) --- title: updateListTree description: Update an existing list tree. full: true --- mutation Requires `commerce.product:write`. Update an existing list tree. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationUpdateListTreeInput!` **required** * `description` `String` **optional** * `htmlDescription` `String` **optional** * `HTMLDescription` `String` **optional** — Deprecated: Use htmlDescription instead. * `label` `String` **optional** * `metafields` `[UpsertMetafieldInput!]` **optional** * `key` `String!` **required** * `namespace` `String!` **required** * `type` `String!` **required** * `value` `String!` **required** * `name` `String` **optional** — Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). * `status` `String` **optional** — The status of the list tree, one of `ACTIVE`, `ARCHIVED`, `DRAFT`. ## Possible returns * `ListTree` `ListTree` — A List tree holds the hierarchical information of a group of lists. - `activatedAt` `DateTime` **nullable** — The timestamp of when the list tree was activated. - `archivedAt` `DateTime` **nullable** — The timestamp of when the list tree was archived. - `createdAt` `DateTime` **nullable** — The creation date of the list tree. - `description` `String` **nullable** — The description of the list tree. - `htmlDescription` `String` **nullable** — HTML description for the List Tree. Will be used to display rich text content to customers. - `id` `ID` **nullable** — The globally-unique ID of the list tree. - `label` `String` **nullable** — The display label of the list tree. - `listTreeNodes` `ListTreeListTreeNodesConnection` **nullable** — List tree node is associated to a single List and a node can be a parent node to provide the hierarchy of list trees. - `metafields` `ListTreeMetafieldsConnection` **nullable** - `name` `String` **nullable** — A unique name of the list tree. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `references` `ListTreeReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `status` `String` **nullable** — The status of the list tree, one of `ACTIVE`, `ARCHIVED`, `DRAFT`. - `updatedAt` `DateTime` **nullable** — The last update date of the list tree. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the List Tree. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. # updateListTreeNode (https://developer.godaddy.com/en/docs/references/rest/catalog/list/mutations/updateListTreeNode) --- title: updateListTreeNode description: Update an existing list tree node. full: true --- mutation Requires `commerce.product:write`. Update an existing list tree node. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationUpdateListTreeNodeInput!` **required** * `listId` `String` **optional** * `listTreeId` `String` **optional** * `parentNodeId` `String` **optional** * `position` `Int` **optional** ## Possible returns * `ListTreeNode` `ListTreeNode` — List tree node is associated to a single List and a node can be a parent node to provide the hierarchy of list trees. - `createdAt` `DateTime` **nullable** — The creation date of the list node. - `id` `ID` **nullable** — The globally-unique ID of the list node. - `list` `List` **nullable** — The list associated with the node. - `listTree` `ListTree` **nullable** — The List Tree associated with the node. - `listTreeNodes` `ListTreeNodeListTreeNodesConnection` **nullable** — The children nodes of the list node. - `parentListTreeNode` `ListTreeNode` **nullable** — The parent node of the list node. - `position` `Int` **nullable** — The position of the node in the list. - `references` `ListTreeNodeReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `updatedAt` `DateTime` **nullable** — The last update date of the list node. # categoriesListTree (https://developer.godaddy.com/en/docs/references/rest/catalog/list/queries/categoriesListTree) --- title: categoriesListTree description: >- Special list tree to hold the main categories of the store. It cannot be updated or archived. full: true --- query Requires `commerce.product:read`. Special list tree to hold the main categories of the store. It cannot be updated or archived. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments *This field takes no arguments.* ## Possible returns * `ListTree` `ListTree` — A List tree holds the hierarchical information of a group of lists. - `activatedAt` `DateTime` **nullable** — The timestamp of when the list tree was activated. - `archivedAt` `DateTime` **nullable** — The timestamp of when the list tree was archived. - `createdAt` `DateTime` **nullable** — The creation date of the list tree. - `description` `String` **nullable** — The description of the list tree. - `htmlDescription` `String` **nullable** — HTML description for the List Tree. Will be used to display rich text content to customers. - `id` `ID` **nullable** — The globally-unique ID of the list tree. - `label` `String` **nullable** — The display label of the list tree. - `listTreeNodes` `ListTreeListTreeNodesConnection` **nullable** — List tree node is associated to a single List and a node can be a parent node to provide the hierarchy of list trees. - `metafields` `ListTreeMetafieldsConnection` **nullable** - `name` `String` **nullable** — A unique name of the list tree. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `references` `ListTreeReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `status` `String` **nullable** — The status of the list tree, one of `ACTIVE`, `ARCHIVED`, `DRAFT`. - `updatedAt` `DateTime` **nullable** — The last update date of the list tree. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the List Tree. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. # list (https://developer.godaddy.com/en/docs/references/rest/catalog/list/queries/list) --- title: list description: Query `list` on the catalog subgraph (List). full: true --- query Requires `commerce.product:read`. Query `list` on the catalog subgraph (List). ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** ## Possible returns * `List` `List` — A list is a group of SKU groups that are generally organized by similar characteristics. - `createdAt` `DateTime!` **non-null** — The date and time of when the List was created. - `description` `String` **nullable** — A single-line textual description of the List. - `htmlDescription` `String` **nullable** — HTML description for the List. Will be used to display rich text content to customers. - `id` `ID!` **non-null** — The globally-unique ID of the List. - `label` `String` **nullable** — The display label of the List. - `mediaObjects` `ListMediaObjectsConnection` **nullable** — Media can be images, videos, or files - `metafields` `ListMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique name for the List. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `references` `ListReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skuGroups` `ListSkuGroupsConnection` **nullable** — A SKU Group is a grouping of related SKUs. It provides information about all of the SKUs that are sold together on storefronts or devices. - `status` `String` **nullable** — The status of the list, one of `ACTIVE`, `DRAFT`, `ARCHIVED`. - `updatedAt` `DateTime!` **non-null** — The date and time of when the List was updated. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the List. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. - `SKUGroups` `ListSKUGroupsConnection` **nullable** deprecated — A SKU Group is a grouping of related SKUs. It provides information about all of the SKUs that are sold together on storefronts or devices. Deprecated: Use skuGroups instead. # listTree (https://developer.godaddy.com/en/docs/references/rest/catalog/list/queries/listTree) --- title: listTree description: Query `listTree` on the catalog subgraph (List). full: true --- query Requires `commerce.product:read`. Query `listTree` on the catalog subgraph (List). ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** ## Possible returns * `ListTree` `ListTree` — A List tree holds the hierarchical information of a group of lists. - `activatedAt` `DateTime` **nullable** — The timestamp of when the list tree was activated. - `archivedAt` `DateTime` **nullable** — The timestamp of when the list tree was archived. - `createdAt` `DateTime` **nullable** — The creation date of the list tree. - `description` `String` **nullable** — The description of the list tree. - `htmlDescription` `String` **nullable** — HTML description for the List Tree. Will be used to display rich text content to customers. - `id` `ID` **nullable** — The globally-unique ID of the list tree. - `label` `String` **nullable** — The display label of the list tree. - `listTreeNodes` `ListTreeListTreeNodesConnection` **nullable** — List tree node is associated to a single List and a node can be a parent node to provide the hierarchy of list trees. - `metafields` `ListTreeMetafieldsConnection` **nullable** - `name` `String` **nullable** — A unique name of the list tree. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `references` `ListTreeReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `status` `String` **nullable** — The status of the list tree, one of `ACTIVE`, `ARCHIVED`, `DRAFT`. - `updatedAt` `DateTime` **nullable** — The last update date of the list tree. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the List Tree. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. # listTreeNode (https://developer.godaddy.com/en/docs/references/rest/catalog/list/queries/listTreeNode) --- title: listTreeNode description: Query `listTreeNode` on the catalog subgraph (List). full: true --- query Requires `commerce.product:read`. Query `listTreeNode` on the catalog subgraph (List). ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** ## Possible returns * `ListTreeNode` `ListTreeNode` — List tree node is associated to a single List and a node can be a parent node to provide the hierarchy of list trees. - `createdAt` `DateTime` **nullable** — The creation date of the list node. - `id` `ID` **nullable** — The globally-unique ID of the list node. - `list` `List` **nullable** — The list associated with the node. - `listTree` `ListTree` **nullable** — The List Tree associated with the node. - `listTreeNodes` `ListTreeNodeListTreeNodesConnection` **nullable** — The children nodes of the list node. - `parentListTreeNode` `ListTreeNode` **nullable** — The parent node of the list node. - `position` `Int` **nullable** — The position of the node in the list. - `references` `ListTreeNodeReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `updatedAt` `DateTime` **nullable** — The last update date of the list node. # listTreeNodes (https://developer.godaddy.com/en/docs/references/rest/catalog/list/queries/listTreeNodes) --- title: listTreeNodes description: Query `listTreeNodes` on the catalog subgraph (List). full: true --- query Requires `commerce.product:read`. Query `listTreeNodes` on the catalog subgraph (List). ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `after` `String` **optional** * `before` `String` **optional** * `createdAt` `CreatedAtFilter` **optional** * `gt` `String` **optional** * `lt` `String` **optional** * `first` `Int` **optional** * `hasParent` `Boolean` **optional** * `id` `ListTreeNodeIdsFilter` **optional** * `in` `[String!]` **optional** * `last` `Int` **optional** * `listId` `ListIdFilter` **optional** * `eq` `String` **optional** * `in` `[String!]` **optional** * `isNull` `Boolean` **optional** * `listStatus` `ListTreeNodeListStatusFilter` **optional** Default: `{"in":["ACTIVE","DRAFT"]}`. * `eq` `String` **optional** * `in` `[String!]` **optional** * `listTreeId` `ListTreeIdFilter` **optional** * `eq` `String` **optional** * `listTreeStatus` `ListTreeNodeListTreeStatusFilter` **optional** * `eq` `String` **optional** * `in` `[String!]` **optional** * `orderBy` `ListTreeNodeOrderBy` **optional** * `createdAt` `OrderByDirectionEnum` **optional** * `id` `OrderByDirectionEnum` **optional** * `position` `OrderByDirectionEnum` **optional** * `updatedAt` `OrderByDirectionEnum` **optional** * `paginationType` `PaginationType` **optional** Default: `"CURSOR"`. * `parentNodeId` `ListTreeNodeParentNodeIdFilter` **optional** * `eq` `String` **optional** * `referenceValue` `ReferenceValueFilter` **optional** * `eq` `String` **optional** * `in` `[String!]` **optional** * `updatedAt` `UpdatedAtFilter` **optional** * `gt` `String` **optional** * `lt` `String` **optional** ## Possible returns * `QueryListTreeNodesConnection` `QueryListTreeNodesConnection` - `edges` `[QueryListTreeNodesConnectionEdge]` **nullable** - `pageInfo` `PageInfo!` **non-null** - `totalCount` `Int!` **non-null** # listTrees (https://developer.godaddy.com/en/docs/references/rest/catalog/list/queries/listTrees) --- title: listTrees description: List trees. Excludes the special categories list tree. full: true --- query Requires `commerce.product:read`. List trees. Excludes the special categories list tree. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `after` `String` **optional** * `before` `String` **optional** * `createdAt` `CreatedAtFilter` **optional** * `gt` `String` **optional** * `lt` `String` **optional** * `first` `Int` **optional** * `id` `ListTreeIdsFilter` **optional** * `in` `[String!]` **optional** * `last` `Int` **optional** * `name` `NameFilter` **optional** * `contains` `String` **optional** — Filters items where the name contains the specified string, case-insensitive. * `eq` `String` **optional** * `in` `[String!]` **optional** — Filters items where the name matches any of the specified names. * `orderBy` `ListTreeOrderBy` **optional** * `createdAt` `OrderByDirectionEnum` **optional** * `id` `OrderByDirectionEnum` **optional** * `name` `OrderByDirectionEnum` **optional** * `updatedAt` `OrderByDirectionEnum` **optional** * `paginationType` `PaginationType` **optional** Default: `"CURSOR"`. * `referenceValue` `ReferenceValueFilter` **optional** * `eq` `String` **optional** * `in` `[String!]` **optional** * `status` `ListTreeStatusFilter` **optional** * `eq` `String` **optional** * `in` `[String!]` **optional** * `updatedAt` `UpdatedAtFilter` **optional** * `gt` `String` **optional** * `lt` `String` **optional** ## Possible returns * `QueryListTreesConnection` `QueryListTreesConnection` - `edges` `[QueryListTreesConnectionEdge]` **nullable** - `pageInfo` `PageInfo!` **non-null** - `totalCount` `Int!` **non-null** # lists (https://developer.godaddy.com/en/docs/references/rest/catalog/list/queries/lists) --- title: lists description: Query `lists` on the catalog subgraph (List). full: true --- query Requires `commerce.product:read`. Query `lists` on the catalog subgraph (List). ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `after` `String` **optional** * `before` `String` **optional** * `createdAt` `CreatedAtFilter` **optional** * `gt` `String` **optional** * `lt` `String` **optional** * `first` `Int` **optional** * `id` `ListIdsFilter` **optional** * `in` `[String!]` **optional** * `last` `Int` **optional** * `name` `NameFilter` **optional** * `contains` `String` **optional** — Filters items where the name contains the specified string, case-insensitive. * `eq` `String` **optional** * `in` `[String!]` **optional** — Filters items where the name matches any of the specified names. * `orderBy` `ListOrderBy` **optional** * `createdAt` `OrderByDirectionEnum` **optional** * `id` `OrderByDirectionEnum` **optional** * `label` `OrderByDirectionEnum` **optional** * `name` `OrderByDirectionEnum` **optional** * `updatedAt` `OrderByDirectionEnum` **optional** * `paginationType` `PaginationType` **optional** Default: `"CURSOR"`. * `referenceValue` `ReferenceValueFilter` **optional** * `eq` `String` **optional** * `in` `[String!]` **optional** * `skuGroupId` `SKUGroupIdFilter` **optional** * `eq` `String` **optional** * `in` `[String!]` **optional** * `status` `ListStatusFilter` **optional** * `eq` `String` **optional** * `in` `[String!]` **optional** * `updatedAt` `UpdatedAtFilter` **optional** * `gt` `String` **optional** * `lt` `String` **optional** ## Possible returns * `QueryListsConnection` `QueryListsConnection` - `edges` `[QueryListsConnectionEdge]` **nullable** - `pageInfo` `PageInfo!` **non-null** - `totalCount` `Int!` **non-null** # addMediaObjectsToList (https://developer.godaddy.com/en/docs/references/rest/catalog/media/mutations/addMediaObjectsToList) --- title: addMediaObjectsToList description: Add media objects to an existing List. full: true --- mutation Requires `commerce.product:write`. Add media objects to an existing List. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationAddMediaObjectsToListInput!` **required** * `mediaObjects` `[CreateMediaObjectInput!]!` **required** * `type` `String!` **required** — The type of the media, one of `IMAGE`, `VIDEO`, `AUDIO`. * `url` `String!` **required** * `label` `String` **optional** * `metafields` `[CreateMetafieldInput!]` **optional** * `key` `String!` **required** * `namespace` `String!` **required** * `type` `String!` **required** — Metafield value type. Live catalog validation accepts lowercase values such as `boolean`, `string`, `stringMultiLine`, `number`, `numberDecimal`, `date`, `dateTime`, `json`, `measurement`, `url`, `reference`, `money`, `list.string`, `list.number`, `list.numberDecimal`. Uppercase `STRING` is rejected. * `value` `String!` **required** * `name` `String` **optional** — Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). * `position` `Int` **optional** ## Possible returns * `List` `List` — A list is a group of SKU groups that are generally organized by similar characteristics. - `createdAt` `DateTime!` **non-null** — The date and time of when the List was created. - `description` `String` **nullable** — A single-line textual description of the List. - `htmlDescription` `String` **nullable** — HTML description for the List. Will be used to display rich text content to customers. - `id` `ID!` **non-null** — The globally-unique ID of the List. - `label` `String` **nullable** — The display label of the List. - `mediaObjects` `ListMediaObjectsConnection` **nullable** — Media can be images, videos, or files - `metafields` `ListMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique name for the List. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `references` `ListReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skuGroups` `ListSkuGroupsConnection` **nullable** — A SKU Group is a grouping of related SKUs. It provides information about all of the SKUs that are sold together on storefronts or devices. - `status` `String` **nullable** — The status of the list, one of `ACTIVE`, `DRAFT`, `ARCHIVED`. - `updatedAt` `DateTime!` **non-null** — The date and time of when the List was updated. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the List. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. - `SKUGroups` `ListSKUGroupsConnection` **nullable** deprecated — A SKU Group is a grouping of related SKUs. It provides information about all of the SKUs that are sold together on storefronts or devices. Deprecated: Use skuGroups instead. # addMediaObjectsToSku (https://developer.godaddy.com/en/docs/references/rest/catalog/media/mutations/addMediaObjectsToSku) --- title: addMediaObjectsToSku description: Add media objects to an existing SKU full: true --- mutation Requires `commerce.product:write`. Add media objects to an existing SKU ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationAddMediaObjectsToSkuInput!` **required** * `mediaObjects` `[CreateMediaObjectInput!]!` **required** * `type` `String!` **required** — The type of the media, one of `IMAGE`, `VIDEO`, `AUDIO`. * `url` `String!` **required** * `label` `String` **optional** * `metafields` `[CreateMetafieldInput!]` **optional** * `key` `String!` **required** * `namespace` `String!` **required** * `type` `String!` **required** — Metafield value type. Live catalog validation accepts lowercase values such as `boolean`, `string`, `stringMultiLine`, `number`, `numberDecimal`, `date`, `dateTime`, `json`, `measurement`, `url`, `reference`, `money`, `list.string`, `list.number`, `list.numberDecimal`. Uppercase `STRING` is rejected. * `value` `String!` **required** * `name` `String` **optional** — Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). * `position` `Int` **optional** ## Possible returns * `SKU` `SKU` — A SKU represents a stock keeping unit (SKU) in the catalog. - `archivedAt` `DateTime` **nullable** — The timestamp of when the SKU was archived. - `attributes` `SKUAttributesConnection` **nullable** — Attributes are properties or characteristics of the SKU. For example, color or size. - `attributeValues` `SKUAttributeValuesConnection` **nullable** — Attribute values of SKU. - `backorderLimit` `Int` **nullable** — The number of backorders allowed for the SKU. If set to 0, backorders are not allowed. If set to null, backorders are allowed without limit. - `code` `String!` **non-null** — The unique code for the SKU. - `createdAt` `DateTime!` **non-null** — The timestamp of when the SKU was created. - `description` `String` **nullable** — The description of the SKU. - `disableInventoryTracking` `Boolean` **nullable** — Flag to mark whether stock should be tracked for the SKU. - `disablePriceOverrides` `Boolean` **nullable** — Flag to mark whether or not a custom price can be provided. - `disableShipping` `Boolean` **nullable** — Flag to mark whether the SKU should be shipped or not. - `eanCode` `String` **nullable** — The EAN code for the SKU. - `gtinCode` `String` **nullable** — The GTIN code for the SKU. - `htmlDescription` `String` **nullable** — HTML description for the SKU. Will be used to display rich text content to customers. - `id` `ID!` **non-null** — The globally-unique ID of the SKU. - `inventoryAdjustments` `SKUInventoryAdjustmentsConnection` **nullable** — An immutable entity that represents a change in state of a quantity of SKU at a particular time and location. Each adjustment will either have a positive, negative, or neutral impact on the count of available SKUs in a location. - `inventoryCounts` `SKUInventoryCountsConnection` **nullable** — The quantity of a SKU in a specific state at a particular time and location. - `isbnCode` `String` **nullable** — The ISBN code for the SKU. - `label` `String` **nullable** — The display label of the SKU. - `locations` `SKULocationsConnection` **nullable** — The locations where the SKU is available. - `mediaObjects` `SKUMediaObjectsConnection` **nullable** — Media stored under this SKU. - `metafields` `SKUMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique name for the SKU. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `prices` `SKUPricesConnection` **nullable** — These are all the prices the SKU can be sold at. The price can be different based the channel where it is listed or if there is a promotion running. - `references` `SKUReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skuGroup` `SKUGroup` **nullable** — A SKU group is a grouping of related SKUs. It provides information about all the SKUs that are sold together on storefronts or devices. - `status` `String` **nullable** — The status of the SKU, one of `DRAFT`, `ACTIVE`, `ARCHIVED`. - `unitCost` `SimpleMoney` **nullable** — The cost of the SKU per unit. This is a money object that includes the value and currency code. - `unitOfWeight` `String` **nullable** — The unit of weight, one of `KG`, `GR`, `LB`, `OZ`. - `upcCode` `String` **nullable** — The UPC code for the SKU. - `updatedAt` `DateTime!` **non-null** — The timestamp of when the SKU was updated. - `weight` `Float` **nullable** — The weight of the SKU. - `cost` `Int` **nullable** deprecated — DEPRECATED. Use unitCost instead. Deprecated: This cost field cannot specify currency code. Use `unitCost` instead. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the SKU. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. - `shortLabel` `String` **nullable** deprecated — A short label for the SKU, useful for UI with limited space. Deprecated: Use channel-specific overrides for short labels. - `SKUGroup` `SKUGroup` **nullable** deprecated — A SKU group is a grouping of related SKUs. It provides information about all the SKUs that are sold together on storefronts or devices. Deprecated: Use skuGroup instead. # addMediaObjectsToSkuGroup (https://developer.godaddy.com/en/docs/references/rest/catalog/media/mutations/addMediaObjectsToSkuGroup) --- title: addMediaObjectsToSkuGroup description: Add media objects to an existing SKU group. full: true --- mutation Requires `commerce.product:write`. Add media objects to an existing SKU group. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationAddMediaObjectsToSkuGroupInput!` **required** * `mediaObjects` `[CreateMediaObjectInput!]!` **required** * `type` `String!` **required** — The type of the media, one of `IMAGE`, `VIDEO`, `AUDIO`. * `url` `String!` **required** * `label` `String` **optional** * `metafields` `[CreateMetafieldInput!]` **optional** * `key` `String!` **required** * `namespace` `String!` **required** * `type` `String!` **required** — Metafield value type. Live catalog validation accepts lowercase values such as `boolean`, `string`, `stringMultiLine`, `number`, `numberDecimal`, `date`, `dateTime`, `json`, `measurement`, `url`, `reference`, `money`, `list.string`, `list.number`, `list.numberDecimal`. Uppercase `STRING` is rejected. * `value` `String!` **required** * `name` `String` **optional** — Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). * `position` `Int` **optional** ## Possible returns * `SKUGroup` `SKUGroup` - `activatedAt` `DateTime` **nullable** — The timestamp of when the SKU was activated. - `archivedAt` `DateTime` **nullable** — The timestamp of when the SKU was archived. - `attributes` `SKUGroupAttributesConnection` **nullable** — Attributes of SKU Group. - `channelAssociationMode` `String` **nullable** — The channel association mode for this SKU Group. Can be ALL (uses active channels registered to the store) or SELECTIVE (uses custom channel associations). - `channels` `SKUGroupChannelsConnection` **nullable** — An association to a channel that exists in the Channel API. - `compareAtPriceRange` `PriceRange` **nullable** — The compare-at price range of the SKU group, showing min and max compare-at prices of SKUs in the group. - `createdAt` `DateTime!` **non-null** — The timestamp of when the SKU was created. - `description` `String` **nullable** — The merchant defined description of the group. - `htmlDescription` `String` **nullable** — HTML description for the SKU group. Will be used to display rich text content to customers. - `id` `ID!` **non-null** — The globally-unique ID of the group. - `label` `String` **nullable** — The display label of the group. - `lists` `SKUGroupListsConnection` **nullable** — A list is a group of SKU groups that are generally organized by similar characteristics. - `mediaObjects` `SKUGroupMediaObjectsConnection` **nullable** — Media objects stored under the SKU Group. - `metafields` `SKUGroupMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique human-friendly identifier for the group. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `options` `SKUGroupOptionsConnection` **nullable** — An option is a add-on that can be added on to a SKU group. - `priceRange` `PriceRange` **nullable** — The price range of the SKU group, showing min and max prices of SKUs in the group. - `references` `SKUGroupReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skuCount` `Int` **nullable** — The count of all SKUs associated with the SKU Group. Can be filtered by status. The default statuses are ACTIVE and DRAFT. - `skus` `SKUGroupSkusConnection` **nullable** — A SKU represents a stock keeping unit (SKU) in the catalog. - `status` `String!` **non-null** — The status of the SKU Group, one of `DRAFT`, `ACTIVE`, `ARCHIVED`. - `type` `String!` **non-null** — The type of the SKU Group, typically PHYSICAL or DIGITAL, but can also be a custom type. - `updatedAt` `DateTime!` **non-null** — The timestamp of when the SKU was updated. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the SKU group. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. - `shortLabel` `String` **nullable** deprecated — A short label for the group. Can be used instead of the label on smaller screens. Deprecated: Use channel-specific overrides for short labels. - `SKUs` `SKUGroupSKUsConnection` **nullable** deprecated — A SKU represents a stock keeping unit (SKU) in the catalog. Deprecated: Use skus instead. # removeMediaObjectsFromList (https://developer.godaddy.com/en/docs/references/rest/catalog/media/mutations/removeMediaObjectsFromList) --- title: removeMediaObjectsFromList description: Remove media objects from an existing List. full: true --- mutation Requires `commerce.product:write`. Remove media objects from an existing List. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationRemoveMediaObjectsFromListInput!` **required** * `mediaObjectIds` `[String!]!` **required** ## Possible returns * `List` `List` — A list is a group of SKU groups that are generally organized by similar characteristics. - `createdAt` `DateTime!` **non-null** — The date and time of when the List was created. - `description` `String` **nullable** — A single-line textual description of the List. - `htmlDescription` `String` **nullable** — HTML description for the List. Will be used to display rich text content to customers. - `id` `ID!` **non-null** — The globally-unique ID of the List. - `label` `String` **nullable** — The display label of the List. - `mediaObjects` `ListMediaObjectsConnection` **nullable** — Media can be images, videos, or files - `metafields` `ListMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique name for the List. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `references` `ListReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skuGroups` `ListSkuGroupsConnection` **nullable** — A SKU Group is a grouping of related SKUs. It provides information about all of the SKUs that are sold together on storefronts or devices. - `status` `String` **nullable** — The status of the list, one of `ACTIVE`, `DRAFT`, `ARCHIVED`. - `updatedAt` `DateTime!` **non-null** — The date and time of when the List was updated. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the List. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. - `SKUGroups` `ListSKUGroupsConnection` **nullable** deprecated — A SKU Group is a grouping of related SKUs. It provides information about all of the SKUs that are sold together on storefronts or devices. Deprecated: Use skuGroups instead. # removeMediaObjectsFromSku (https://developer.godaddy.com/en/docs/references/rest/catalog/media/mutations/removeMediaObjectsFromSku) --- title: removeMediaObjectsFromSku description: Remove media objects from an existing SKU full: true --- mutation Requires `commerce.product:write`. Remove media objects from an existing SKU ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationRemoveMediaObjectsFromSkuInput!` **required** * `mediaObjectIds` `[String!]!` **required** ## Possible returns * `SKU` `SKU` — A SKU represents a stock keeping unit (SKU) in the catalog. - `archivedAt` `DateTime` **nullable** — The timestamp of when the SKU was archived. - `attributes` `SKUAttributesConnection` **nullable** — Attributes are properties or characteristics of the SKU. For example, color or size. - `attributeValues` `SKUAttributeValuesConnection` **nullable** — Attribute values of SKU. - `backorderLimit` `Int` **nullable** — The number of backorders allowed for the SKU. If set to 0, backorders are not allowed. If set to null, backorders are allowed without limit. - `code` `String!` **non-null** — The unique code for the SKU. - `createdAt` `DateTime!` **non-null** — The timestamp of when the SKU was created. - `description` `String` **nullable** — The description of the SKU. - `disableInventoryTracking` `Boolean` **nullable** — Flag to mark whether stock should be tracked for the SKU. - `disablePriceOverrides` `Boolean` **nullable** — Flag to mark whether or not a custom price can be provided. - `disableShipping` `Boolean` **nullable** — Flag to mark whether the SKU should be shipped or not. - `eanCode` `String` **nullable** — The EAN code for the SKU. - `gtinCode` `String` **nullable** — The GTIN code for the SKU. - `htmlDescription` `String` **nullable** — HTML description for the SKU. Will be used to display rich text content to customers. - `id` `ID!` **non-null** — The globally-unique ID of the SKU. - `inventoryAdjustments` `SKUInventoryAdjustmentsConnection` **nullable** — An immutable entity that represents a change in state of a quantity of SKU at a particular time and location. Each adjustment will either have a positive, negative, or neutral impact on the count of available SKUs in a location. - `inventoryCounts` `SKUInventoryCountsConnection` **nullable** — The quantity of a SKU in a specific state at a particular time and location. - `isbnCode` `String` **nullable** — The ISBN code for the SKU. - `label` `String` **nullable** — The display label of the SKU. - `locations` `SKULocationsConnection` **nullable** — The locations where the SKU is available. - `mediaObjects` `SKUMediaObjectsConnection` **nullable** — Media stored under this SKU. - `metafields` `SKUMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique name for the SKU. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `prices` `SKUPricesConnection` **nullable** — These are all the prices the SKU can be sold at. The price can be different based the channel where it is listed or if there is a promotion running. - `references` `SKUReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skuGroup` `SKUGroup` **nullable** — A SKU group is a grouping of related SKUs. It provides information about all the SKUs that are sold together on storefronts or devices. - `status` `String` **nullable** — The status of the SKU, one of `DRAFT`, `ACTIVE`, `ARCHIVED`. - `unitCost` `SimpleMoney` **nullable** — The cost of the SKU per unit. This is a money object that includes the value and currency code. - `unitOfWeight` `String` **nullable** — The unit of weight, one of `KG`, `GR`, `LB`, `OZ`. - `upcCode` `String` **nullable** — The UPC code for the SKU. - `updatedAt` `DateTime!` **non-null** — The timestamp of when the SKU was updated. - `weight` `Float` **nullable** — The weight of the SKU. - `cost` `Int` **nullable** deprecated — DEPRECATED. Use unitCost instead. Deprecated: This cost field cannot specify currency code. Use `unitCost` instead. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the SKU. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. - `shortLabel` `String` **nullable** deprecated — A short label for the SKU, useful for UI with limited space. Deprecated: Use channel-specific overrides for short labels. - `SKUGroup` `SKUGroup` **nullable** deprecated — A SKU group is a grouping of related SKUs. It provides information about all the SKUs that are sold together on storefronts or devices. Deprecated: Use skuGroup instead. # removeMediaObjectsFromSkuGroup (https://developer.godaddy.com/en/docs/references/rest/catalog/media/mutations/removeMediaObjectsFromSkuGroup) --- title: removeMediaObjectsFromSkuGroup description: Remove media objects from an existing SKU group. full: true --- mutation Requires `commerce.product:write`. Remove media objects from an existing SKU group. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationRemoveMediaObjectsFromSkuGroupInput!` **required** * `mediaObjectIds` `[String!]!` **required** ## Possible returns * `SKUGroup` `SKUGroup` - `activatedAt` `DateTime` **nullable** — The timestamp of when the SKU was activated. - `archivedAt` `DateTime` **nullable** — The timestamp of when the SKU was archived. - `attributes` `SKUGroupAttributesConnection` **nullable** — Attributes of SKU Group. - `channelAssociationMode` `String` **nullable** — The channel association mode for this SKU Group. Can be ALL (uses active channels registered to the store) or SELECTIVE (uses custom channel associations). - `channels` `SKUGroupChannelsConnection` **nullable** — An association to a channel that exists in the Channel API. - `compareAtPriceRange` `PriceRange` **nullable** — The compare-at price range of the SKU group, showing min and max compare-at prices of SKUs in the group. - `createdAt` `DateTime!` **non-null** — The timestamp of when the SKU was created. - `description` `String` **nullable** — The merchant defined description of the group. - `htmlDescription` `String` **nullable** — HTML description for the SKU group. Will be used to display rich text content to customers. - `id` `ID!` **non-null** — The globally-unique ID of the group. - `label` `String` **nullable** — The display label of the group. - `lists` `SKUGroupListsConnection` **nullable** — A list is a group of SKU groups that are generally organized by similar characteristics. - `mediaObjects` `SKUGroupMediaObjectsConnection` **nullable** — Media objects stored under the SKU Group. - `metafields` `SKUGroupMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique human-friendly identifier for the group. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `options` `SKUGroupOptionsConnection` **nullable** — An option is a add-on that can be added on to a SKU group. - `priceRange` `PriceRange` **nullable** — The price range of the SKU group, showing min and max prices of SKUs in the group. - `references` `SKUGroupReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skuCount` `Int` **nullable** — The count of all SKUs associated with the SKU Group. Can be filtered by status. The default statuses are ACTIVE and DRAFT. - `skus` `SKUGroupSkusConnection` **nullable** — A SKU represents a stock keeping unit (SKU) in the catalog. - `status` `String!` **non-null** — The status of the SKU Group, one of `DRAFT`, `ACTIVE`, `ARCHIVED`. - `type` `String!` **non-null** — The type of the SKU Group, typically PHYSICAL or DIGITAL, but can also be a custom type. - `updatedAt` `DateTime!` **non-null** — The timestamp of when the SKU was updated. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the SKU group. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. - `shortLabel` `String` **nullable** deprecated — A short label for the group. Can be used instead of the label on smaller screens. Deprecated: Use channel-specific overrides for short labels. - `SKUs` `SKUGroupSKUsConnection` **nullable** deprecated — A SKU represents a stock keeping unit (SKU) in the catalog. Deprecated: Use skus instead. # updateListMediaObjects (https://developer.godaddy.com/en/docs/references/rest/catalog/media/mutations/updateListMediaObjects) --- title: updateListMediaObjects description: Add media objects or update existing media objects to existing List. full: true --- mutation Requires `commerce.product:write`. Add media objects or update existing media objects to existing List. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationUpdateListMediaObjectsInput!` **required** * `mediaObjects` `[UpdateMediaObjectInput!]!` **required** * `id` `String!` **required** * `label` `String` **optional** * `metafields` `[UpsertMetafieldInput!]` **optional** * `key` `String!` **required** * `namespace` `String!` **required** * `type` `String!` **required** * `value` `String!` **required** * `name` `String` **optional** — Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). * `position` `Int` **optional** * `type` `String` **optional** — The type of the media, one of `IMAGE`, `VIDEO`, `AUDIO`. * `url` `String` **optional** ## Possible returns * `List` `List` — A list is a group of SKU groups that are generally organized by similar characteristics. - `createdAt` `DateTime!` **non-null** — The date and time of when the List was created. - `description` `String` **nullable** — A single-line textual description of the List. - `htmlDescription` `String` **nullable** — HTML description for the List. Will be used to display rich text content to customers. - `id` `ID!` **non-null** — The globally-unique ID of the List. - `label` `String` **nullable** — The display label of the List. - `mediaObjects` `ListMediaObjectsConnection` **nullable** — Media can be images, videos, or files - `metafields` `ListMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique name for the List. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `references` `ListReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skuGroups` `ListSkuGroupsConnection` **nullable** — A SKU Group is a grouping of related SKUs. It provides information about all of the SKUs that are sold together on storefronts or devices. - `status` `String` **nullable** — The status of the list, one of `ACTIVE`, `DRAFT`, `ARCHIVED`. - `updatedAt` `DateTime!` **non-null** — The date and time of when the List was updated. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the List. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. - `SKUGroups` `ListSKUGroupsConnection` **nullable** deprecated — A SKU Group is a grouping of related SKUs. It provides information about all of the SKUs that are sold together on storefronts or devices. Deprecated: Use skuGroups instead. # updateSkuGroupMediaObjects (https://developer.godaddy.com/en/docs/references/rest/catalog/media/mutations/updateSkuGroupMediaObjects) --- title: updateSkuGroupMediaObjects description: Add media objects or update existing media objects to existing SKU Group. full: true --- mutation Requires `commerce.product:write`. Add media objects or update existing media objects to existing SKU Group. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationUpdateSkuGroupMediaObjectsInput!` **required** * `mediaObjects` `[UpdateMediaObjectInput!]!` **required** * `id` `String!` **required** * `label` `String` **optional** * `metafields` `[UpsertMetafieldInput!]` **optional** * `key` `String!` **required** * `namespace` `String!` **required** * `type` `String!` **required** * `value` `String!` **required** * `name` `String` **optional** — Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). * `position` `Int` **optional** * `type` `String` **optional** — The type of the media, one of `IMAGE`, `VIDEO`, `AUDIO`. * `url` `String` **optional** ## Possible returns * `SKUGroup` `SKUGroup` - `activatedAt` `DateTime` **nullable** — The timestamp of when the SKU was activated. - `archivedAt` `DateTime` **nullable** — The timestamp of when the SKU was archived. - `attributes` `SKUGroupAttributesConnection` **nullable** — Attributes of SKU Group. - `channelAssociationMode` `String` **nullable** — The channel association mode for this SKU Group. Can be ALL (uses active channels registered to the store) or SELECTIVE (uses custom channel associations). - `channels` `SKUGroupChannelsConnection` **nullable** — An association to a channel that exists in the Channel API. - `compareAtPriceRange` `PriceRange` **nullable** — The compare-at price range of the SKU group, showing min and max compare-at prices of SKUs in the group. - `createdAt` `DateTime!` **non-null** — The timestamp of when the SKU was created. - `description` `String` **nullable** — The merchant defined description of the group. - `htmlDescription` `String` **nullable** — HTML description for the SKU group. Will be used to display rich text content to customers. - `id` `ID!` **non-null** — The globally-unique ID of the group. - `label` `String` **nullable** — The display label of the group. - `lists` `SKUGroupListsConnection` **nullable** — A list is a group of SKU groups that are generally organized by similar characteristics. - `mediaObjects` `SKUGroupMediaObjectsConnection` **nullable** — Media objects stored under the SKU Group. - `metafields` `SKUGroupMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique human-friendly identifier for the group. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `options` `SKUGroupOptionsConnection` **nullable** — An option is a add-on that can be added on to a SKU group. - `priceRange` `PriceRange` **nullable** — The price range of the SKU group, showing min and max prices of SKUs in the group. - `references` `SKUGroupReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skuCount` `Int` **nullable** — The count of all SKUs associated with the SKU Group. Can be filtered by status. The default statuses are ACTIVE and DRAFT. - `skus` `SKUGroupSkusConnection` **nullable** — A SKU represents a stock keeping unit (SKU) in the catalog. - `status` `String!` **non-null** — The status of the SKU Group, one of `DRAFT`, `ACTIVE`, `ARCHIVED`. - `type` `String!` **non-null** — The type of the SKU Group, typically PHYSICAL or DIGITAL, but can also be a custom type. - `updatedAt` `DateTime!` **non-null** — The timestamp of when the SKU was updated. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the SKU group. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. - `shortLabel` `String` **nullable** deprecated — A short label for the group. Can be used instead of the label on smaller screens. Deprecated: Use channel-specific overrides for short labels. - `SKUs` `SKUGroupSKUsConnection` **nullable** deprecated — A SKU represents a stock keeping unit (SKU) in the catalog. Deprecated: Use skus instead. # updateSkuMediaObjects (https://developer.godaddy.com/en/docs/references/rest/catalog/media/mutations/updateSkuMediaObjects) --- title: updateSkuMediaObjects description: Add media objects or update existing media objects to existing SKU. full: true --- mutation Requires `commerce.product:write`. Add media objects or update existing media objects to existing SKU. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationUpdateSkuMediaObjectsInput!` **required** * `mediaObjects` `[UpdateMediaObjectInput!]!` **required** * `id` `String!` **required** * `label` `String` **optional** * `metafields` `[UpsertMetafieldInput!]` **optional** * `key` `String!` **required** * `namespace` `String!` **required** * `type` `String!` **required** * `value` `String!` **required** * `name` `String` **optional** — Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). * `position` `Int` **optional** * `type` `String` **optional** — The type of the media, one of `IMAGE`, `VIDEO`, `AUDIO`. * `url` `String` **optional** ## Possible returns * `SKU` `SKU` — A SKU represents a stock keeping unit (SKU) in the catalog. - `archivedAt` `DateTime` **nullable** — The timestamp of when the SKU was archived. - `attributes` `SKUAttributesConnection` **nullable** — Attributes are properties or characteristics of the SKU. For example, color or size. - `attributeValues` `SKUAttributeValuesConnection` **nullable** — Attribute values of SKU. - `backorderLimit` `Int` **nullable** — The number of backorders allowed for the SKU. If set to 0, backorders are not allowed. If set to null, backorders are allowed without limit. - `code` `String!` **non-null** — The unique code for the SKU. - `createdAt` `DateTime!` **non-null** — The timestamp of when the SKU was created. - `description` `String` **nullable** — The description of the SKU. - `disableInventoryTracking` `Boolean` **nullable** — Flag to mark whether stock should be tracked for the SKU. - `disablePriceOverrides` `Boolean` **nullable** — Flag to mark whether or not a custom price can be provided. - `disableShipping` `Boolean` **nullable** — Flag to mark whether the SKU should be shipped or not. - `eanCode` `String` **nullable** — The EAN code for the SKU. - `gtinCode` `String` **nullable** — The GTIN code for the SKU. - `htmlDescription` `String` **nullable** — HTML description for the SKU. Will be used to display rich text content to customers. - `id` `ID!` **non-null** — The globally-unique ID of the SKU. - `inventoryAdjustments` `SKUInventoryAdjustmentsConnection` **nullable** — An immutable entity that represents a change in state of a quantity of SKU at a particular time and location. Each adjustment will either have a positive, negative, or neutral impact on the count of available SKUs in a location. - `inventoryCounts` `SKUInventoryCountsConnection` **nullable** — The quantity of a SKU in a specific state at a particular time and location. - `isbnCode` `String` **nullable** — The ISBN code for the SKU. - `label` `String` **nullable** — The display label of the SKU. - `locations` `SKULocationsConnection` **nullable** — The locations where the SKU is available. - `mediaObjects` `SKUMediaObjectsConnection` **nullable** — Media stored under this SKU. - `metafields` `SKUMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique name for the SKU. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `prices` `SKUPricesConnection` **nullable** — These are all the prices the SKU can be sold at. The price can be different based the channel where it is listed or if there is a promotion running. - `references` `SKUReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skuGroup` `SKUGroup` **nullable** — A SKU group is a grouping of related SKUs. It provides information about all the SKUs that are sold together on storefronts or devices. - `status` `String` **nullable** — The status of the SKU, one of `DRAFT`, `ACTIVE`, `ARCHIVED`. - `unitCost` `SimpleMoney` **nullable** — The cost of the SKU per unit. This is a money object that includes the value and currency code. - `unitOfWeight` `String` **nullable** — The unit of weight, one of `KG`, `GR`, `LB`, `OZ`. - `upcCode` `String` **nullable** — The UPC code for the SKU. - `updatedAt` `DateTime!` **non-null** — The timestamp of when the SKU was updated. - `weight` `Float` **nullable** — The weight of the SKU. - `cost` `Int` **nullable** deprecated — DEPRECATED. Use unitCost instead. Deprecated: This cost field cannot specify currency code. Use `unitCost` instead. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the SKU. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. - `shortLabel` `String` **nullable** deprecated — A short label for the SKU, useful for UI with limited space. Deprecated: Use channel-specific overrides for short labels. - `SKUGroup` `SKUGroup` **nullable** deprecated — A SKU group is a grouping of related SKUs. It provides information about all the SKUs that are sold together on storefronts or devices. Deprecated: Use skuGroup instead. # createOption (https://developer.godaddy.com/en/docs/references/rest/catalog/option/mutations/createOption) --- title: createOption description: Create a new option. full: true --- mutation Requires `commerce.product:write`. Create a new option. ## Prerequisites * **`skuGroupIds`** — include at least one SKU group id. Standalone `createOption` calls fail without it (`Non-sharable options require at least one skuGroupId`). * Get ids from [`skuGroups`](https://developer.godaddy.com/docs/references/rest/catalog/sku-group/queries/skuGroups) or [`createSkuGroup`](https://developer.godaddy.com/docs/references/rest/catalog/sku-group/mutations/createSkuGroup). Prefer `skuGroupIds` over deprecated `skuGroupId`. Send `type` as `TEXT`, `NUMBER`, or `LIST` — not `NUMERIC`. `NUMBER` returns `NumericOption`. `min`/`max` live on `validation` (no `step` field). For `SimpleMoneyInput.value`, send `1999` for $19.99 USD, not `19.99`. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `input` `MutationCreateOptionInput!` **required** * `label` `String!` **required** * `type` `String!` **required** — The type of the Option, one of `TEXT`, `NUMBER`, `LIST`. Option Values are only available on the 'LIST' type. * `description` `String` **optional** * `htmlDescription` `String` **optional** * `HTMLDescription` `String` **optional** — Deprecated: Use htmlDescription instead. * `metafields` `[CreateMetafieldInput!]` **optional** * `key` `String!` **required** * `namespace` `String!` **required** * `type` `String!` **required** — Metafield value type. Live catalog validation accepts lowercase values such as `boolean`, `string`, `stringMultiLine`, `number`, `numberDecimal`, `date`, `dateTime`, `json`, `measurement`, `url`, `reference`, `money`, `list.string`, `list.number`, `list.numberDecimal`. Uppercase `STRING` is rejected. * `value` `String!` **required** * `name` `String` **optional** — Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). * `position` `Int` **optional** * `prices` `[CreateOptionPriceInput!]` **optional** * `value` `SimpleMoneyInput!` **required** * `currencyCode` `String!` **required** * `value` `Float!` **required** — Integer minor units in the smallest currency unit (for USD, cents: `1999` = $19.99). Send `1999`, not `19.99`. * `compareAtValue` `SimpleMoneyInput` **optional** * `currencyCode` `String!` **required** * `value` `Float!` **required** — Integer minor units in the smallest currency unit (for USD, cents: `1999` = $19.99). Send `1999`, not `19.99`. * `shareable` `Boolean` **optional** — Whether this option is shareable across multiple SKU Groups. * `skuGroupId` `String` **optional** — Deprecated: Use skuGroupIds instead. * `skuGroupIds` `[String!]` **optional** — The UUIDs of the SKU Groups to associate the Option with. * `validation` `CreateOptionValidationInput` **optional** * `max` `Int` **optional** * `min` `Int` **optional** * `values` `[CreateOptionValueInput!]` **optional** * `label` `String!` **required** * `metafields` `[CreateMetafieldInput!]` **optional** * `key` `String!` **required** * `namespace` `String!` **required** * `type` `String!` **required** — Metafield value type. Live catalog validation accepts lowercase values such as `boolean`, `string`, `stringMultiLine`, `number`, `numberDecimal`, `date`, `dateTime`, `json`, `measurement`, `url`, `reference`, `money`, `list.string`, `list.number`, `list.numberDecimal`. Uppercase `STRING` is rejected. * `value` `String!` **required** * `name` `String` **optional** — Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). * `position` `Int` **optional** * `prices` `[CreateOptionValuePriceInput!]` **optional** * `value` `SimpleMoneyInput!` **required** * `compareAtValue` `SimpleMoneyInput` **optional** ## Possible returns * `Option` `Option` # createOptionPrice (https://developer.godaddy.com/en/docs/references/rest/catalog/option/mutations/createOptionPrice) --- title: createOptionPrice description: >- Create a flat price for the option. This will be ignored if a price is present on the option values. full: true --- mutation Requires `commerce.product:write`. Create a flat price for the option. This will be ignored if a price is present on the option values. For `SimpleMoneyInput.value`, send `1999` for $19.99 USD, not `19.99`. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `input` `MutationCreateOptionPriceInput!` **required** * `optionId` `String!` **required** * `value` `SimpleMoneyInput!` **required** * `currencyCode` `String!` **required** * `value` `Float!` **required** — Integer minor units in the smallest currency unit (for USD, cents: `1999` = $19.99). Send `1999`, not `19.99`. * `compareAtValue` `SimpleMoneyInput` **optional** * `currencyCode` `String!` **required** * `value` `Float!` **required** — Integer minor units in the smallest currency unit (for USD, cents: `1999` = $19.99). Send `1999`, not `19.99`. ## Possible returns * `OptionPrice` `OptionPrice` — Represents the additional cost of an option added to a SKU group (e.g 'Toppings' option for a coffee drink). - `compareAtValue` `SimpleMoney` **nullable** — The compare-at value of the price. - `createdAt` `DateTime!` **non-null** — The timestamp of when the price was created. - `id` `ID!` **non-null** — The globally-unique ID of the price. - `option` `Option` **nullable** — The option that this price belongs to. - `updatedAt` `DateTime!` **non-null** — The last update timestamp of the price. - `value` `SimpleMoney!` **non-null** — The value of the price. # createOptionValue (https://developer.godaddy.com/en/docs/references/rest/catalog/option/mutations/createOptionValue) --- title: createOptionValue description: Create a new option value. full: true --- mutation Requires `commerce.product:write`. Create a new option value. For `SimpleMoneyInput.value`, send `1999` for $19.99 USD, not `19.99`. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `input` `MutationCreateOptionValueInput!` **required** * `label` `String!` **required** * `optionId` `String!` **required** * `metafields` `[CreateMetafieldInput!]` **optional** * `key` `String!` **required** * `namespace` `String!` **required** * `type` `String!` **required** — Metafield value type. Live catalog validation accepts lowercase values such as `boolean`, `string`, `stringMultiLine`, `number`, `numberDecimal`, `date`, `dateTime`, `json`, `measurement`, `url`, `reference`, `money`, `list.string`, `list.number`, `list.numberDecimal`. Uppercase `STRING` is rejected. * `value` `String!` **required** * `name` `String` **optional** — Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). * `position` `Int` **optional** * `prices` `[CreateOptionValuePriceInput!]` **optional** * `value` `SimpleMoneyInput!` **required** * `currencyCode` `String!` **required** * `value` `Float!` **required** — Integer minor units in the smallest currency unit (for USD, cents: `1999` = $19.99). Send `1999`, not `19.99`. * `compareAtValue` `SimpleMoneyInput` **optional** * `currencyCode` `String!` **required** * `value` `Float!` **required** — Integer minor units in the smallest currency unit (for USD, cents: `1999` = $19.99). Send `1999`, not `19.99`. ## Possible returns * `OptionValue` `OptionValue` - `createdAt` `DateTime!` **non-null** — The timestamp of when the Option Value was created. - `id` `ID!` **non-null** — The UUID of the Option Value. - `label` `String` **nullable** — The display label of the Option Value. - `metafields` `OptionValueMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique name of the Option Value. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `option` `ListOption` **nullable** — The option that this value belongs to. - `position` `Int` **nullable** — The position of the option value. - `prices` `OptionValuePricesConnection` **nullable** — These are all the prices the Option Value can be sold at. The price can be different based the channel where it is listed or if there is a promotion running. - `updatedAt` `DateTime!` **non-null** — The timestamp of when the Option Value was updated. # createOptionValuePrice (https://developer.godaddy.com/en/docs/references/rest/catalog/option/mutations/createOptionValuePrice) --- title: createOptionValuePrice description: Create a price. full: true --- mutation Requires `commerce.product:write`. Create a price. For `SimpleMoneyInput.value`, send `1999` for $19.99 USD, not `19.99`. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `input` `MutationCreateOptionValuePriceInput!` **required** * `optionValueId` `String!` **required** * `value` `SimpleMoneyInput!` **required** * `currencyCode` `String!` **required** * `value` `Float!` **required** — Integer minor units in the smallest currency unit (for USD, cents: `1999` = $19.99). Send `1999`, not `19.99`. * `compareAtValue` `SimpleMoneyInput` **optional** * `currencyCode` `String!` **required** * `value` `Float!` **required** — Integer minor units in the smallest currency unit (for USD, cents: `1999` = $19.99). Send `1999`, not `19.99`. ## Possible returns * `OptionValuePrice` `OptionValuePrice` — Represents the additional cost of the option value added to a SKU (e.g the option value 'Caramel Drizzle' could have a different cost to other 'Topping' options). - `compareAtValue` `SimpleMoney` **nullable** — The compare-at value of the price. - `createdAt` `DateTime!` **non-null** — The timestamp of when the price was created. - `id` `ID!` **non-null** — The globally-unique ID of the price. - `optionValue` `OptionValue` **nullable** — The option value that this price belongs to. - `updatedAt` `DateTime!` **non-null** — The last update timestamp of the price. - `value` `SimpleMoney!` **non-null** — The value of the price. # createOptionValues (https://developer.godaddy.com/en/docs/references/rest/catalog/option/mutations/createOptionValues) --- title: createOptionValues description: Create multiple new Option Values in a single transaction. full: true --- mutation Requires `commerce.product:write`. Create multiple new Option Values in a single transaction. For `SimpleMoneyInput.value`, send `1999` for $19.99 USD, not `19.99`. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `input` `[MutationCreateOptionValueInput!]!` **required** * `label` `String!` **required** * `optionId` `String!` **required** * `metafields` `[CreateMetafieldInput!]` **optional** * `key` `String!` **required** * `namespace` `String!` **required** * `type` `String!` **required** — Metafield value type. Live catalog validation accepts lowercase values such as `boolean`, `string`, `stringMultiLine`, `number`, `numberDecimal`, `date`, `dateTime`, `json`, `measurement`, `url`, `reference`, `money`, `list.string`, `list.number`, `list.numberDecimal`. Uppercase `STRING` is rejected. * `value` `String!` **required** * `name` `String` **optional** — Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). * `position` `Int` **optional** * `prices` `[CreateOptionValuePriceInput!]` **optional** * `value` `SimpleMoneyInput!` **required** * `currencyCode` `String!` **required** * `value` `Float!` **required** — Integer minor units in the smallest currency unit (for USD, cents: `1999` = $19.99). Send `1999`, not `19.99`. * `compareAtValue` `SimpleMoneyInput` **optional** * `currencyCode` `String!` **required** * `value` `Float!` **required** — Integer minor units in the smallest currency unit (for USD, cents: `1999` = $19.99). Send `1999`, not `19.99`. ## Possible returns * `OptionValue` `[OptionValue!]` - `createdAt` `DateTime!` **non-null** — The timestamp of when the Option Value was created. - `id` `ID!` **non-null** — The UUID of the Option Value. - `label` `String` **nullable** — The display label of the Option Value. - `metafields` `OptionValueMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique name of the Option Value. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `option` `ListOption` **nullable** — The option that this value belongs to. - `position` `Int` **nullable** — The position of the option value. - `prices` `OptionValuePricesConnection` **nullable** — These are all the prices the Option Value can be sold at. The price can be different based the channel where it is listed or if there is a promotion running. - `updatedAt` `DateTime!` **non-null** — The timestamp of when the Option Value was updated. # removeMetafieldsFromOption (https://developer.godaddy.com/en/docs/references/rest/catalog/option/mutations/removeMetafieldsFromOption) --- title: removeMetafieldsFromOption description: Remove metafields from an existing Option. full: true --- mutation Requires `commerce.product:write`. Remove metafields from an existing Option. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationRemoveMetafieldsFromOptionInput!` **required** * `metafields` `[RemoveMetafieldInput!]!` **required** * `key` `String!` **required** * `namespace` `String!` **required** ## Possible returns * `Option` `Option` # removeMetafieldsFromOptionValue (https://developer.godaddy.com/en/docs/references/rest/catalog/option/mutations/removeMetafieldsFromOptionValue) --- title: removeMetafieldsFromOptionValue description: Remove metafields from an existing Option Value. full: true --- mutation Requires `commerce.product:write`. Remove metafields from an existing Option Value. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationRemoveMetafieldsFromOptionValueInput!` **required** * `metafields` `[RemoveMetafieldInput!]!` **required** * `key` `String!` **required** * `namespace` `String!` **required** ## Possible returns * `OptionValue` `OptionValue` - `createdAt` `DateTime!` **non-null** — The timestamp of when the Option Value was created. - `id` `ID!` **non-null** — The UUID of the Option Value. - `label` `String` **nullable** — The display label of the Option Value. - `metafields` `OptionValueMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique name of the Option Value. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `option` `ListOption` **nullable** — The option that this value belongs to. - `position` `Int` **nullable** — The position of the option value. - `prices` `OptionValuePricesConnection` **nullable** — These are all the prices the Option Value can be sold at. The price can be different based the channel where it is listed or if there is a promotion running. - `updatedAt` `DateTime!` **non-null** — The timestamp of when the Option Value was updated. # removeOption (https://developer.godaddy.com/en/docs/references/rest/catalog/option/mutations/removeOption) --- title: removeOption description: Remove an existing option. full: true --- mutation Requires `commerce.product:write`. Remove an existing option. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** ## Possible returns * `Null` `Null` # removeOptionValue (https://developer.godaddy.com/en/docs/references/rest/catalog/option/mutations/removeOptionValue) --- title: removeOptionValue description: Remove an existing option value. full: true --- mutation Requires `commerce.product:write`. Remove an existing option value. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** ## Possible returns * `Null` `Null` # removeOptionValuesFromListOption (https://developer.godaddy.com/en/docs/references/rest/catalog/option/mutations/removeOptionValuesFromListOption) --- title: removeOptionValuesFromListOption description: Remove values from an existing Option. full: true --- mutation Requires `commerce.product:write`. Remove values from an existing Option. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationRemoveOptionValuesFromListOptionInput!` **required** * `valueIds` `[String!]!` **required** ## Possible returns * `ListOption` `ListOption` - `compareAtPriceRange` `PriceRange` **nullable** — The `compareAt` price range of the option, tracks the min and max `compareAt` price of all the option values under this option. - `createdAt` `DateTime!` **non-null** — The timestamp of when the Option was created. - `description` `String` **nullable** — A description of the Option. - `id` `ID!` **non-null** — The UUID of the Option - `label` `String` **nullable** — The display lable of the Option - `metafields` `OptionMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique name of the Option. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `priceRange` `PriceRange` **nullable** — The price range of the option, tracks the min and max price of all the option values under this option. - `prices` `ListOptionPricesConnection` **nullable** — Represents the additional cost of a List Option. When empty, it indicates this option allows for flexible pricing. - `shareable` `Boolean!` **non-null** — Whether the option is shareable across multiple SKU Groups (a global modifier). - `skuGroupIds` `[String!]!` **non-null** — The IDs of all SKU groups this option is associated with. - `type` `String` **nullable** — The type of the option, one of `TEXT`, `NUMBER`, `LIST`, Option Values are available for the 'LIST' type. - `updatedAt` `DateTime!` **non-null** — The timestamp of when the Option was updated. - `validation` `OptionValidation` **nullable** — Provide validations on how the option can be applied to a SKU. If `TEXT` option then `min` and `max` apply to the number of characters. If `NUMBER` then `min` and `max` apply to the actual number value. If `LIST` then `min` and `max` apply to the number of values that can be selected. - `values` `ListOptionValuesConnection` **nullable** — Represents the additional cost of a List Option. Each value can have one or more prices. - `position` `Int` **nullable** deprecated — The position of the option within its SKU group. Deprecated: Use the position from the SKUGroup.options connection instead. Position is per-SKU-group relationship. - `skuGroupId` `ID!` **non-null** deprecated — The UUID of the SKU Group that the Option belongs to. Deprecated: Use skuGroupIds or the SKUGroup.options connection instead. An option may belong to multiple SKU groups. # removePricesFromOption (https://developer.godaddy.com/en/docs/references/rest/catalog/option/mutations/removePricesFromOption) --- title: removePricesFromOption description: Remove prices from an existing Option. full: true --- mutation Requires `commerce.product:write`. Remove prices from an existing Option. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationRemovePricesFromOptionInput!` **required** * `priceIds` `[String!]!` **required** ## Possible returns * `Option` `Option` # removePricesFromOptionValue (https://developer.godaddy.com/en/docs/references/rest/catalog/option/mutations/removePricesFromOptionValue) --- title: removePricesFromOptionValue description: Remove prices from an existing OptionValue. full: true --- mutation Requires `commerce.product:write`. Remove prices from an existing OptionValue. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationRemovePricesFromOptionValueInput!` **required** * `priceIds` `[String!]!` **required** ## Possible returns * `OptionValue` `OptionValue` - `createdAt` `DateTime!` **non-null** — The timestamp of when the Option Value was created. - `id` `ID!` **non-null** — The UUID of the Option Value. - `label` `String` **nullable** — The display label of the Option Value. - `metafields` `OptionValueMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique name of the Option Value. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `option` `ListOption` **nullable** — The option that this value belongs to. - `position` `Int` **nullable** — The position of the option value. - `prices` `OptionValuePricesConnection` **nullable** — These are all the prices the Option Value can be sold at. The price can be different based the channel where it is listed or if there is a promotion running. - `updatedAt` `DateTime!` **non-null** — The timestamp of when the Option Value was updated. # updateOption (https://developer.godaddy.com/en/docs/references/rest/catalog/option/mutations/updateOption) --- title: updateOption description: Update an existing option. full: true --- mutation Requires `commerce.product:write`. Update an existing option. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationUpdateOptionInput!` **required** * `description` `String` **optional** * `htmlDescription` `String` **optional** * `HTMLDescription` `String` **optional** — Deprecated: Use htmlDescription instead. * `label` `String` **optional** * `metafields` `[UpsertMetafieldInput!]` **optional** * `key` `String!` **required** * `namespace` `String!` **required** * `type` `String!` **required** * `value` `String!` **required** * `name` `String` **optional** — Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). * `position` `Int` **optional** * `shareable` `Boolean` **optional** * `type` `String` **optional** — The type of the Option, one of `TEXT`, `NUMBER`, `LIST`. Option Values are only available on the 'LIST' type. * `validation` `CreateOptionValidationInput` **optional** * `max` `Int` **optional** * `min` `Int` **optional** ## Possible returns * `Option` `Option` # updateOptionPrice (https://developer.godaddy.com/en/docs/references/rest/catalog/option/mutations/updateOptionPrice) --- title: updateOptionPrice description: Update an existing price object for an option. full: true --- mutation Requires `commerce.product:write`. Update an existing price object for an option. Sending only `value` can clear `compareAtValue`. Include both fields if you need to keep the compare-at price. For `SimpleMoneyInput.value`, send `1999` for $19.99 USD, not `19.99`. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationUpdateOptionPriceInput!` **required** * `compareAtValue` `SimpleMoneyInput` **optional** * `currencyCode` `String!` **required** * `value` `Float!` **required** — Integer minor units in the smallest currency unit (for USD, cents: `1999` = $19.99). Send `1999`, not `19.99`. * `value` `SimpleMoneyInput` **optional** * `currencyCode` `String!` **required** * `value` `Float!` **required** — Integer minor units in the smallest currency unit (for USD, cents: `1999` = $19.99). Send `1999`, not `19.99`. ## Possible returns * `OptionPrice` `OptionPrice` — Represents the additional cost of an option added to a SKU group (e.g 'Toppings' option for a coffee drink). - `compareAtValue` `SimpleMoney` **nullable** — The compare-at value of the price. - `createdAt` `DateTime!` **non-null** — The timestamp of when the price was created. - `id` `ID!` **non-null** — The globally-unique ID of the price. - `option` `Option` **nullable** — The option that this price belongs to. - `updatedAt` `DateTime!` **non-null** — The last update timestamp of the price. - `value` `SimpleMoney!` **non-null** — The value of the price. # updateOptionPriceCurrencyCode (https://developer.godaddy.com/en/docs/references/rest/catalog/option/mutations/updateOptionPriceCurrencyCode) --- title: updateOptionPriceCurrencyCode description: >- Update the currency code for an existing option price. This updates the currency code for both value and compareAtValue. full: true --- mutation Requires `commerce.product:write`. Update the currency code for an existing option price. This updates the currency code for both value and compareAtValue. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationUpdateOptionPriceCurrencyCodeInput!` **required** * `currencyCode` `String!` **required** ## Possible returns * `OptionPrice` `OptionPrice` — Represents the additional cost of an option added to a SKU group (e.g 'Toppings' option for a coffee drink). - `compareAtValue` `SimpleMoney` **nullable** — The compare-at value of the price. - `createdAt` `DateTime!` **non-null** — The timestamp of when the price was created. - `id` `ID!` **non-null** — The globally-unique ID of the price. - `option` `Option` **nullable** — The option that this price belongs to. - `updatedAt` `DateTime!` **non-null** — The last update timestamp of the price. - `value` `SimpleMoney!` **non-null** — The value of the price. # updateOptionValue (https://developer.godaddy.com/en/docs/references/rest/catalog/option/mutations/updateOptionValue) --- title: updateOptionValue description: Update an existing option value. full: true --- mutation Requires `commerce.product:write`. Update an existing option value. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationUpdateOptionValueInput!` **required** * `label` `String` **optional** * `metafields` `[UpsertMetafieldInput!]` **optional** * `key` `String!` **required** * `namespace` `String!` **required** * `type` `String!` **required** * `value` `String!` **required** * `name` `String` **optional** — Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). * `position` `Int` **optional** ## Possible returns * `OptionValue` `OptionValue` - `createdAt` `DateTime!` **non-null** — The timestamp of when the Option Value was created. - `id` `ID!` **non-null** — The UUID of the Option Value. - `label` `String` **nullable** — The display label of the Option Value. - `metafields` `OptionValueMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique name of the Option Value. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `option` `ListOption` **nullable** — The option that this value belongs to. - `position` `Int` **nullable** — The position of the option value. - `prices` `OptionValuePricesConnection` **nullable** — These are all the prices the Option Value can be sold at. The price can be different based the channel where it is listed or if there is a promotion running. - `updatedAt` `DateTime!` **non-null** — The timestamp of when the Option Value was updated. # updateOptionValuePrice (https://developer.godaddy.com/en/docs/references/rest/catalog/option/mutations/updateOptionValuePrice) --- title: updateOptionValuePrice description: Update an existing price object. full: true --- mutation Requires `commerce.product:write`. Update an existing price object. For `SimpleMoneyInput.value`, send `1999` for $19.99 USD, not `19.99`. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationUpdateOptionValuePriceInput!` **required** * `compareAtValue` `SimpleMoneyInput` **optional** * `currencyCode` `String!` **required** * `value` `Float!` **required** — Integer minor units in the smallest currency unit (for USD, cents: `1999` = $19.99). Send `1999`, not `19.99`. * `value` `SimpleMoneyInput` **optional** * `currencyCode` `String!` **required** * `value` `Float!` **required** — Integer minor units in the smallest currency unit (for USD, cents: `1999` = $19.99). Send `1999`, not `19.99`. ## Possible returns * `OptionValuePrice` `OptionValuePrice` — Represents the additional cost of the option value added to a SKU (e.g the option value 'Caramel Drizzle' could have a different cost to other 'Topping' options). - `compareAtValue` `SimpleMoney` **nullable** — The compare-at value of the price. - `createdAt` `DateTime!` **non-null** — The timestamp of when the price was created. - `id` `ID!` **non-null** — The globally-unique ID of the price. - `optionValue` `OptionValue` **nullable** — The option value that this price belongs to. - `updatedAt` `DateTime!` **non-null** — The last update timestamp of the price. - `value` `SimpleMoney!` **non-null** — The value of the price. # updateOptionValuePriceCurrencyCode (https://developer.godaddy.com/en/docs/references/rest/catalog/option/mutations/updateOptionValuePriceCurrencyCode) --- title: updateOptionValuePriceCurrencyCode description: >- Update the currency code for an existing option value price. This updates the currency code for both value and compareAtValue. full: true --- mutation Requires `commerce.product:write`. Update the currency code for an existing option value price. This updates the currency code for both value and compareAtValue. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationUpdateOptionValuePriceCurrencyCodeInput!` **required** * `currencyCode` `String!` **required** ## Possible returns * `OptionValuePrice` `OptionValuePrice` — Represents the additional cost of the option value added to a SKU (e.g the option value 'Caramel Drizzle' could have a different cost to other 'Topping' options). - `compareAtValue` `SimpleMoney` **nullable** — The compare-at value of the price. - `createdAt` `DateTime!` **non-null** — The timestamp of when the price was created. - `id` `ID!` **non-null** — The globally-unique ID of the price. - `optionValue` `OptionValue` **nullable** — The option value that this price belongs to. - `updatedAt` `DateTime!` **non-null** — The last update timestamp of the price. - `value` `SimpleMoney!` **non-null** — The value of the price. # optionPrices (https://developer.godaddy.com/en/docs/references/rest/catalog/option/queries/optionPrices) --- title: optionPrices description: Query all option prices. full: true --- query Requires `commerce.product:read`. Query all option prices. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `after` `String` **optional** * `before` `String` **optional** * `currencyCode` `CurrencyCodeFilter` **optional** — Filter prices by currency code. * `eq` `String` **optional** — Filters items where the currency code equals the specified 3-letter ISO currency code. * `in` `[String!]` **optional** — Filters items where the currency code matches any of the specified 3-letter ISO currency codes. * `first` `Int` **optional** * `id` `OptionPriceIdsFilter` **optional** * `in` `[String!]` **optional** * `last` `Int` **optional** * `optionId` `OptionIdFilter` **optional** * `eq` `String` **optional** * `in` `[String!]` **optional** * `orderBy` `OptionPriceOrderBy` **optional** * `id` `OrderByDirectionEnum` **optional** * `updatedAt` `OrderByDirectionEnum` **optional** * `paginationType` `PaginationType` **optional** Default: `"CURSOR"`. * `updatedAt` `UpdatedAtFilter` **optional** * `gt` `String` **optional** * `lt` `String` **optional** ## Possible returns * `QueryOptionPricesConnection` `QueryOptionPricesConnection` - `edges` `[QueryOptionPricesConnectionEdge]` **nullable** - `pageInfo` `PageInfo!` **non-null** - `totalCount` `Int!` **non-null** # optionValuePrices (https://developer.godaddy.com/en/docs/references/rest/catalog/option/queries/optionValuePrices) --- title: optionValuePrices description: Query all option value prices. full: true --- query Requires `commerce.product:read`. Query all option value prices. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `after` `String` **optional** * `before` `String` **optional** * `currencyCode` `CurrencyCodeFilter` **optional** — Filter prices by currency code. * `eq` `String` **optional** — Filters items where the currency code equals the specified 3-letter ISO currency code. * `in` `[String!]` **optional** — Filters items where the currency code matches any of the specified 3-letter ISO currency codes. * `first` `Int` **optional** * `id` `OptionValuePriceIdsFilter` **optional** * `in` `[String!]` **optional** * `last` `Int` **optional** * `optionValueId` `OptionValueIdFilter` **optional** * `eq` `String` **optional** * `orderBy` `OptionValuePriceOrderBy` **optional** * `id` `OrderByDirectionEnum` **optional** * `updatedAt` `OrderByDirectionEnum` **optional** * `paginationType` `PaginationType` **optional** Default: `"CURSOR"`. * `updatedAt` `UpdatedAtFilter` **optional** * `gt` `String` **optional** * `lt` `String` **optional** ## Possible returns * `QueryOptionValuePricesConnection` `QueryOptionValuePricesConnection` - `edges` `[QueryOptionValuePricesConnectionEdge]` **nullable** - `pageInfo` `PageInfo!` **non-null** - `totalCount` `Int!` **non-null** # optionValues (https://developer.godaddy.com/en/docs/references/rest/catalog/option/queries/optionValues) --- title: optionValues description: Query `optionValues` on the catalog subgraph (Option). full: true --- query Requires `commerce.product:read`. Query `optionValues` on the catalog subgraph (Option). ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `after` `String` **optional** * `before` `String` **optional** * `createdAt` `CreatedAtFilter` **optional** * `gt` `String` **optional** * `lt` `String` **optional** * `first` `Int` **optional** * `id` `OptionValueIdsFilter` **optional** * `in` `[String!]` **optional** * `last` `Int` **optional** * `optionId` `OptionIdFilter` **optional** * `eq` `String` **optional** * `in` `[String!]` **optional** * `orderBy` `OptionValueOrderBy` **optional** * `createdAt` `OrderByDirectionEnum` **optional** * `id` `OrderByDirectionEnum` **optional** * `name` `OrderByDirectionEnum` **optional** * `position` `OrderByDirectionEnum` **optional** * `price` `OrderByDirectionEnum` **optional** * `updatedAt` `OrderByDirectionEnum` **optional** * `paginationType` `PaginationType` **optional** Default: `"CURSOR"`. * `updatedAt` `UpdatedAtFilter` **optional** * `gt` `String` **optional** * `lt` `String` **optional** ## Possible returns * `QueryOptionValuesConnection` `QueryOptionValuesConnection` - `edges` `[QueryOptionValuesConnectionEdge]` **nullable** - `pageInfo` `PageInfo!` **non-null** - `totalCount` `Int!` **non-null** # options (https://developer.godaddy.com/en/docs/references/rest/catalog/option/queries/options) --- title: options description: Query `options` on the catalog subgraph (Option). full: true --- query Requires `commerce.product:read`. Query `options` on the catalog subgraph (Option). ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `after` `String` **optional** * `assignableToSkuGroupId` `String` **optional** — Returns shareable options that are not already associated with the specified SKU group. Use this to find options that can be added to a SKU group. Cannot be combined with skuGroupId or skuGroupStatus filters. * `before` `String` **optional** * `createdAt` `CreatedAtFilter` **optional** * `gt` `String` **optional** * `lt` `String` **optional** * `first` `Int` **optional** * `id` `OptionIdsFilter` **optional** * `in` `[String!]` **optional** * `label` `LabelFilter` **optional** * `contains` `String` **optional** — Filters items where the label contains the specified string, case-insensitive. * `eq` `String` **optional** * `last` `Int` **optional** * `name` `NameFilter` **optional** * `contains` `String` **optional** — Filters items where the name contains the specified string, case-insensitive. * `eq` `String` **optional** * `in` `[String!]` **optional** — Filters items where the name matches any of the specified names. * `orderBy` `OptionOrderBy` **optional** * `createdAt` `OrderByDirectionEnum` **optional** * `id` `OrderByDirectionEnum` **optional** * `label` `OrderByDirectionEnum` **optional** * `name` `OrderByDirectionEnum` **optional** * `position` `OrderByDirectionEnum` **optional** * `price` `OrderByDirectionEnum` **optional** * `updatedAt` `OrderByDirectionEnum` **optional** * `paginationType` `PaginationType` **optional** Default: `"CURSOR"`. * `shareable` `Boolean` **optional** — Filter options by their shareable status. When true, returns only shareable options; when false, returns only non-shareable options. * `skuGroupId` `SKUGroupIdFilter` **optional** * `eq` `String` **optional** * `in` `[String!]` **optional** * `skuGroupStatus` `SKUGroupStatusFilter` **optional** * `eq` `String` **optional** * `in` `[String!]` **optional** * `updatedAt` `UpdatedAtFilter` **optional** * `gt` `String` **optional** * `lt` `String` **optional** ## Possible returns * `QueryOptionsConnection` `QueryOptionsConnection` - `edges` `[QueryOptionsConnectionEdge]` **nullable** - `pageInfo` `PageInfo!` **non-null** - `totalCount` `Int!` **non-null** # addReferencesToList (https://developer.godaddy.com/en/docs/references/rest/catalog/reference/mutations/addReferencesToList) --- title: addReferencesToList description: Add references to an existing List. full: true --- mutation Requires `commerce.product:write`. Add references to an existing List. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationAddReferencesToListInput!` **required** * `references` `[CreateReferenceInput!]!` **required** * `origin` `String!` **required** * `value` `String!` **required** ## Possible returns * `List` `List` — A list is a group of SKU groups that are generally organized by similar characteristics. - `createdAt` `DateTime!` **non-null** — The date and time of when the List was created. - `description` `String` **nullable** — A single-line textual description of the List. - `htmlDescription` `String` **nullable** — HTML description for the List. Will be used to display rich text content to customers. - `id` `ID!` **non-null** — The globally-unique ID of the List. - `label` `String` **nullable** — The display label of the List. - `mediaObjects` `ListMediaObjectsConnection` **nullable** — Media can be images, videos, or files - `metafields` `ListMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique name for the List. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `references` `ListReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skuGroups` `ListSkuGroupsConnection` **nullable** — A SKU Group is a grouping of related SKUs. It provides information about all of the SKUs that are sold together on storefronts or devices. - `status` `String` **nullable** — The status of the list, one of `ACTIVE`, `DRAFT`, `ARCHIVED`. - `updatedAt` `DateTime!` **non-null** — The date and time of when the List was updated. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the List. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. - `SKUGroups` `ListSKUGroupsConnection` **nullable** deprecated — A SKU Group is a grouping of related SKUs. It provides information about all of the SKUs that are sold together on storefronts or devices. Deprecated: Use skuGroups instead. # addReferencesToListTree (https://developer.godaddy.com/en/docs/references/rest/catalog/reference/mutations/addReferencesToListTree) --- title: addReferencesToListTree description: Add references to an existing List Tree. full: true --- mutation Requires `commerce.product:write`. Add references to an existing List Tree. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationAddReferencesToListTreeInput!` **required** * `references` `[CreateReferenceInput!]!` **required** * `origin` `String!` **required** * `value` `String!` **required** ## Possible returns * `ListTree` `ListTree` — A List tree holds the hierarchical information of a group of lists. - `activatedAt` `DateTime` **nullable** — The timestamp of when the list tree was activated. - `archivedAt` `DateTime` **nullable** — The timestamp of when the list tree was archived. - `createdAt` `DateTime` **nullable** — The creation date of the list tree. - `description` `String` **nullable** — The description of the list tree. - `htmlDescription` `String` **nullable** — HTML description for the List Tree. Will be used to display rich text content to customers. - `id` `ID` **nullable** — The globally-unique ID of the list tree. - `label` `String` **nullable** — The display label of the list tree. - `listTreeNodes` `ListTreeListTreeNodesConnection` **nullable** — List tree node is associated to a single List and a node can be a parent node to provide the hierarchy of list trees. - `metafields` `ListTreeMetafieldsConnection` **nullable** - `name` `String` **nullable** — A unique name of the list tree. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `references` `ListTreeReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `status` `String` **nullable** — The status of the list tree, one of `ACTIVE`, `ARCHIVED`, `DRAFT`. - `updatedAt` `DateTime` **nullable** — The last update date of the list tree. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the List Tree. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. # addReferencesToLocation (https://developer.godaddy.com/en/docs/references/rest/catalog/reference/mutations/addReferencesToLocation) --- title: addReferencesToLocation description: Add references to an existing location. full: true --- mutation Requires `commerce.product:write`. Add references to an existing location. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationAddReferencesToLocationInput!` **required** * `references` `[CreateReferenceInput!]!` **required** * `origin` `String!` **required** * `value` `String!` **required** ## Possible returns * `Location` `Location` — A location represents the physical location of an inventory. - `address` `Address` **nullable** — The address of the Location. - `createdAt` `DateTime!` **non-null** — The timestamp of when the Location was created. - `id` `ID!` **non-null** — The globally-unique ID of the Location. - `inventoryAdjustments` `LocationInventoryAdjustmentsConnection` **nullable** — An immutable entity that represents a change in state of a quantity of SKU at a particular time and location. Each adjustment will either have a positive, negative, or neutral impact on the count of available SKUs in a location. - `inventoryCounts` `LocationInventoryCountsConnection` **nullable** — The quantity of a SKU in a specific state at a particular time and location. - `label` `String` **nullable** — The display name of the Location. - `metafields` `LocationMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique and human-friendly name of the Location. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `references` `LocationReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skus` `LocationSkusConnection` **nullable** — The SKUs are purchasable items in the catalog. - `status` `String!` **non-null** — The status of the location, one of `ACTIVE`, `INACTIVE`, `ARCHIVED`. - `updatedAt` `DateTime!` **non-null** — The timestamp of when the Location was updated. - `SKUs` `LocationSKUsConnection` **nullable** deprecated — The SKUs are purchasable items in the catalog. Deprecated: Use skus instead. # addReferencesToSku (https://developer.godaddy.com/en/docs/references/rest/catalog/reference/mutations/addReferencesToSku) --- title: addReferencesToSku description: Add references to an existing SKU. full: true --- mutation Requires `commerce.product:write`. Add references to an existing SKU. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationAddReferencesToSkuInput!` **required** * `references` `[CreateReferenceInput!]!` **required** * `origin` `String!` **required** * `value` `String!` **required** ## Possible returns * `SKU` `SKU` — A SKU represents a stock keeping unit (SKU) in the catalog. - `archivedAt` `DateTime` **nullable** — The timestamp of when the SKU was archived. - `attributes` `SKUAttributesConnection` **nullable** — Attributes are properties or characteristics of the SKU. For example, color or size. - `attributeValues` `SKUAttributeValuesConnection` **nullable** — Attribute values of SKU. - `backorderLimit` `Int` **nullable** — The number of backorders allowed for the SKU. If set to 0, backorders are not allowed. If set to null, backorders are allowed without limit. - `code` `String!` **non-null** — The unique code for the SKU. - `createdAt` `DateTime!` **non-null** — The timestamp of when the SKU was created. - `description` `String` **nullable** — The description of the SKU. - `disableInventoryTracking` `Boolean` **nullable** — Flag to mark whether stock should be tracked for the SKU. - `disablePriceOverrides` `Boolean` **nullable** — Flag to mark whether or not a custom price can be provided. - `disableShipping` `Boolean` **nullable** — Flag to mark whether the SKU should be shipped or not. - `eanCode` `String` **nullable** — The EAN code for the SKU. - `gtinCode` `String` **nullable** — The GTIN code for the SKU. - `htmlDescription` `String` **nullable** — HTML description for the SKU. Will be used to display rich text content to customers. - `id` `ID!` **non-null** — The globally-unique ID of the SKU. - `inventoryAdjustments` `SKUInventoryAdjustmentsConnection` **nullable** — An immutable entity that represents a change in state of a quantity of SKU at a particular time and location. Each adjustment will either have a positive, negative, or neutral impact on the count of available SKUs in a location. - `inventoryCounts` `SKUInventoryCountsConnection` **nullable** — The quantity of a SKU in a specific state at a particular time and location. - `isbnCode` `String` **nullable** — The ISBN code for the SKU. - `label` `String` **nullable** — The display label of the SKU. - `locations` `SKULocationsConnection` **nullable** — The locations where the SKU is available. - `mediaObjects` `SKUMediaObjectsConnection` **nullable** — Media stored under this SKU. - `metafields` `SKUMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique name for the SKU. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `prices` `SKUPricesConnection` **nullable** — These are all the prices the SKU can be sold at. The price can be different based the channel where it is listed or if there is a promotion running. - `references` `SKUReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skuGroup` `SKUGroup` **nullable** — A SKU group is a grouping of related SKUs. It provides information about all the SKUs that are sold together on storefronts or devices. - `status` `String` **nullable** — The status of the SKU, one of `DRAFT`, `ACTIVE`, `ARCHIVED`. - `unitCost` `SimpleMoney` **nullable** — The cost of the SKU per unit. This is a money object that includes the value and currency code. - `unitOfWeight` `String` **nullable** — The unit of weight, one of `KG`, `GR`, `LB`, `OZ`. - `upcCode` `String` **nullable** — The UPC code for the SKU. - `updatedAt` `DateTime!` **non-null** — The timestamp of when the SKU was updated. - `weight` `Float` **nullable** — The weight of the SKU. - `cost` `Int` **nullable** deprecated — DEPRECATED. Use unitCost instead. Deprecated: This cost field cannot specify currency code. Use `unitCost` instead. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the SKU. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. - `shortLabel` `String` **nullable** deprecated — A short label for the SKU, useful for UI with limited space. Deprecated: Use channel-specific overrides for short labels. - `SKUGroup` `SKUGroup` **nullable** deprecated — A SKU group is a grouping of related SKUs. It provides information about all the SKUs that are sold together on storefronts or devices. Deprecated: Use skuGroup instead. # addReferencesToSkuGroup (https://developer.godaddy.com/en/docs/references/rest/catalog/reference/mutations/addReferencesToSkuGroup) --- title: addReferencesToSkuGroup description: Add references to an existing SKU group. full: true --- mutation Requires `commerce.product:write`. Add references to an existing SKU group. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationAddReferencesToSkuGroupInput!` **required** * `references` `[CreateReferenceInput!]!` **required** * `origin` `String!` **required** * `value` `String!` **required** ## Possible returns * `SKUGroup` `SKUGroup` - `activatedAt` `DateTime` **nullable** — The timestamp of when the SKU was activated. - `archivedAt` `DateTime` **nullable** — The timestamp of when the SKU was archived. - `attributes` `SKUGroupAttributesConnection` **nullable** — Attributes of SKU Group. - `channelAssociationMode` `String` **nullable** — The channel association mode for this SKU Group. Can be ALL (uses active channels registered to the store) or SELECTIVE (uses custom channel associations). - `channels` `SKUGroupChannelsConnection` **nullable** — An association to a channel that exists in the Channel API. - `compareAtPriceRange` `PriceRange` **nullable** — The compare-at price range of the SKU group, showing min and max compare-at prices of SKUs in the group. - `createdAt` `DateTime!` **non-null** — The timestamp of when the SKU was created. - `description` `String` **nullable** — The merchant defined description of the group. - `htmlDescription` `String` **nullable** — HTML description for the SKU group. Will be used to display rich text content to customers. - `id` `ID!` **non-null** — The globally-unique ID of the group. - `label` `String` **nullable** — The display label of the group. - `lists` `SKUGroupListsConnection` **nullable** — A list is a group of SKU groups that are generally organized by similar characteristics. - `mediaObjects` `SKUGroupMediaObjectsConnection` **nullable** — Media objects stored under the SKU Group. - `metafields` `SKUGroupMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique human-friendly identifier for the group. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `options` `SKUGroupOptionsConnection` **nullable** — An option is a add-on that can be added on to a SKU group. - `priceRange` `PriceRange` **nullable** — The price range of the SKU group, showing min and max prices of SKUs in the group. - `references` `SKUGroupReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skuCount` `Int` **nullable** — The count of all SKUs associated with the SKU Group. Can be filtered by status. The default statuses are ACTIVE and DRAFT. - `skus` `SKUGroupSkusConnection` **nullable** — A SKU represents a stock keeping unit (SKU) in the catalog. - `status` `String!` **non-null** — The status of the SKU Group, one of `DRAFT`, `ACTIVE`, `ARCHIVED`. - `type` `String!` **non-null** — The type of the SKU Group, typically PHYSICAL or DIGITAL, but can also be a custom type. - `updatedAt` `DateTime!` **non-null** — The timestamp of when the SKU was updated. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the SKU group. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. - `shortLabel` `String` **nullable** deprecated — A short label for the group. Can be used instead of the label on smaller screens. Deprecated: Use channel-specific overrides for short labels. - `SKUs` `SKUGroupSKUsConnection` **nullable** deprecated — A SKU represents a stock keeping unit (SKU) in the catalog. Deprecated: Use skus instead. # removeReferencesFromList (https://developer.godaddy.com/en/docs/references/rest/catalog/reference/mutations/removeReferencesFromList) --- title: removeReferencesFromList description: Remove references from an existing List. full: true --- mutation Requires `commerce.product:write`. Remove references from an existing List. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationRemoveReferencesFromListInput!` **required** * `referenceIds` `[String!]!` **required** ## Possible returns * `List` `List` — A list is a group of SKU groups that are generally organized by similar characteristics. - `createdAt` `DateTime!` **non-null** — The date and time of when the List was created. - `description` `String` **nullable** — A single-line textual description of the List. - `htmlDescription` `String` **nullable** — HTML description for the List. Will be used to display rich text content to customers. - `id` `ID!` **non-null** — The globally-unique ID of the List. - `label` `String` **nullable** — The display label of the List. - `mediaObjects` `ListMediaObjectsConnection` **nullable** — Media can be images, videos, or files - `metafields` `ListMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique name for the List. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `references` `ListReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skuGroups` `ListSkuGroupsConnection` **nullable** — A SKU Group is a grouping of related SKUs. It provides information about all of the SKUs that are sold together on storefronts or devices. - `status` `String` **nullable** — The status of the list, one of `ACTIVE`, `DRAFT`, `ARCHIVED`. - `updatedAt` `DateTime!` **non-null** — The date and time of when the List was updated. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the List. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. - `SKUGroups` `ListSKUGroupsConnection` **nullable** deprecated — A SKU Group is a grouping of related SKUs. It provides information about all of the SKUs that are sold together on storefronts or devices. Deprecated: Use skuGroups instead. # removeReferencesFromListTree (https://developer.godaddy.com/en/docs/references/rest/catalog/reference/mutations/removeReferencesFromListTree) --- title: removeReferencesFromListTree description: Remove references from an existing List Tree full: true --- mutation Requires `commerce.product:write`. Remove references from an existing List Tree ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationRemoveReferencesFromListTreeInput!` **required** * `referenceIds` `[String!]!` **required** ## Possible returns * `ListTree` `ListTree` — A List tree holds the hierarchical information of a group of lists. - `activatedAt` `DateTime` **nullable** — The timestamp of when the list tree was activated. - `archivedAt` `DateTime` **nullable** — The timestamp of when the list tree was archived. - `createdAt` `DateTime` **nullable** — The creation date of the list tree. - `description` `String` **nullable** — The description of the list tree. - `htmlDescription` `String` **nullable** — HTML description for the List Tree. Will be used to display rich text content to customers. - `id` `ID` **nullable** — The globally-unique ID of the list tree. - `label` `String` **nullable** — The display label of the list tree. - `listTreeNodes` `ListTreeListTreeNodesConnection` **nullable** — List tree node is associated to a single List and a node can be a parent node to provide the hierarchy of list trees. - `metafields` `ListTreeMetafieldsConnection` **nullable** - `name` `String` **nullable** — A unique name of the list tree. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `references` `ListTreeReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `status` `String` **nullable** — The status of the list tree, one of `ACTIVE`, `ARCHIVED`, `DRAFT`. - `updatedAt` `DateTime` **nullable** — The last update date of the list tree. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the List Tree. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. # removeReferencesFromLocation (https://developer.godaddy.com/en/docs/references/rest/catalog/reference/mutations/removeReferencesFromLocation) --- title: removeReferencesFromLocation description: Remove references from an existing location. full: true --- mutation Requires `commerce.product:write`. Remove references from an existing location. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationRemoveReferencesFromLocationInput!` **required** * `referenceIds` `[String!]!` **required** ## Possible returns * `Location` `Location` — A location represents the physical location of an inventory. - `address` `Address` **nullable** — The address of the Location. - `createdAt` `DateTime!` **non-null** — The timestamp of when the Location was created. - `id` `ID!` **non-null** — The globally-unique ID of the Location. - `inventoryAdjustments` `LocationInventoryAdjustmentsConnection` **nullable** — An immutable entity that represents a change in state of a quantity of SKU at a particular time and location. Each adjustment will either have a positive, negative, or neutral impact on the count of available SKUs in a location. - `inventoryCounts` `LocationInventoryCountsConnection` **nullable** — The quantity of a SKU in a specific state at a particular time and location. - `label` `String` **nullable** — The display name of the Location. - `metafields` `LocationMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique and human-friendly name of the Location. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `references` `LocationReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skus` `LocationSkusConnection` **nullable** — The SKUs are purchasable items in the catalog. - `status` `String!` **non-null** — The status of the location, one of `ACTIVE`, `INACTIVE`, `ARCHIVED`. - `updatedAt` `DateTime!` **non-null** — The timestamp of when the Location was updated. - `SKUs` `LocationSKUsConnection` **nullable** deprecated — The SKUs are purchasable items in the catalog. Deprecated: Use skus instead. # removeReferencesFromSku (https://developer.godaddy.com/en/docs/references/rest/catalog/reference/mutations/removeReferencesFromSku) --- title: removeReferencesFromSku description: Remove references from an existing SKU. full: true --- mutation Requires `commerce.product:write`. Remove references from an existing SKU. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationRemoveReferencesFromSkuInput!` **required** * `referenceIds` `[String!]!` **required** ## Possible returns * `SKU` `SKU` — A SKU represents a stock keeping unit (SKU) in the catalog. - `archivedAt` `DateTime` **nullable** — The timestamp of when the SKU was archived. - `attributes` `SKUAttributesConnection` **nullable** — Attributes are properties or characteristics of the SKU. For example, color or size. - `attributeValues` `SKUAttributeValuesConnection` **nullable** — Attribute values of SKU. - `backorderLimit` `Int` **nullable** — The number of backorders allowed for the SKU. If set to 0, backorders are not allowed. If set to null, backorders are allowed without limit. - `code` `String!` **non-null** — The unique code for the SKU. - `createdAt` `DateTime!` **non-null** — The timestamp of when the SKU was created. - `description` `String` **nullable** — The description of the SKU. - `disableInventoryTracking` `Boolean` **nullable** — Flag to mark whether stock should be tracked for the SKU. - `disablePriceOverrides` `Boolean` **nullable** — Flag to mark whether or not a custom price can be provided. - `disableShipping` `Boolean` **nullable** — Flag to mark whether the SKU should be shipped or not. - `eanCode` `String` **nullable** — The EAN code for the SKU. - `gtinCode` `String` **nullable** — The GTIN code for the SKU. - `htmlDescription` `String` **nullable** — HTML description for the SKU. Will be used to display rich text content to customers. - `id` `ID!` **non-null** — The globally-unique ID of the SKU. - `inventoryAdjustments` `SKUInventoryAdjustmentsConnection` **nullable** — An immutable entity that represents a change in state of a quantity of SKU at a particular time and location. Each adjustment will either have a positive, negative, or neutral impact on the count of available SKUs in a location. - `inventoryCounts` `SKUInventoryCountsConnection` **nullable** — The quantity of a SKU in a specific state at a particular time and location. - `isbnCode` `String` **nullable** — The ISBN code for the SKU. - `label` `String` **nullable** — The display label of the SKU. - `locations` `SKULocationsConnection` **nullable** — The locations where the SKU is available. - `mediaObjects` `SKUMediaObjectsConnection` **nullable** — Media stored under this SKU. - `metafields` `SKUMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique name for the SKU. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `prices` `SKUPricesConnection` **nullable** — These are all the prices the SKU can be sold at. The price can be different based the channel where it is listed or if there is a promotion running. - `references` `SKUReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skuGroup` `SKUGroup` **nullable** — A SKU group is a grouping of related SKUs. It provides information about all the SKUs that are sold together on storefronts or devices. - `status` `String` **nullable** — The status of the SKU, one of `DRAFT`, `ACTIVE`, `ARCHIVED`. - `unitCost` `SimpleMoney` **nullable** — The cost of the SKU per unit. This is a money object that includes the value and currency code. - `unitOfWeight` `String` **nullable** — The unit of weight, one of `KG`, `GR`, `LB`, `OZ`. - `upcCode` `String` **nullable** — The UPC code for the SKU. - `updatedAt` `DateTime!` **non-null** — The timestamp of when the SKU was updated. - `weight` `Float` **nullable** — The weight of the SKU. - `cost` `Int` **nullable** deprecated — DEPRECATED. Use unitCost instead. Deprecated: This cost field cannot specify currency code. Use `unitCost` instead. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the SKU. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. - `shortLabel` `String` **nullable** deprecated — A short label for the SKU, useful for UI with limited space. Deprecated: Use channel-specific overrides for short labels. - `SKUGroup` `SKUGroup` **nullable** deprecated — A SKU group is a grouping of related SKUs. It provides information about all the SKUs that are sold together on storefronts or devices. Deprecated: Use skuGroup instead. # removeReferencesFromSkuGroup (https://developer.godaddy.com/en/docs/references/rest/catalog/reference/mutations/removeReferencesFromSkuGroup) --- title: removeReferencesFromSkuGroup description: Remove references from an existing SKU group. full: true --- mutation Requires `commerce.product:write`. Remove references from an existing SKU group. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationRemoveReferencesFromSkuGroupInput!` **required** * `referenceIds` `[String!]!` **required** ## Possible returns * `SKUGroup` `SKUGroup` - `activatedAt` `DateTime` **nullable** — The timestamp of when the SKU was activated. - `archivedAt` `DateTime` **nullable** — The timestamp of when the SKU was archived. - `attributes` `SKUGroupAttributesConnection` **nullable** — Attributes of SKU Group. - `channelAssociationMode` `String` **nullable** — The channel association mode for this SKU Group. Can be ALL (uses active channels registered to the store) or SELECTIVE (uses custom channel associations). - `channels` `SKUGroupChannelsConnection` **nullable** — An association to a channel that exists in the Channel API. - `compareAtPriceRange` `PriceRange` **nullable** — The compare-at price range of the SKU group, showing min and max compare-at prices of SKUs in the group. - `createdAt` `DateTime!` **non-null** — The timestamp of when the SKU was created. - `description` `String` **nullable** — The merchant defined description of the group. - `htmlDescription` `String` **nullable** — HTML description for the SKU group. Will be used to display rich text content to customers. - `id` `ID!` **non-null** — The globally-unique ID of the group. - `label` `String` **nullable** — The display label of the group. - `lists` `SKUGroupListsConnection` **nullable** — A list is a group of SKU groups that are generally organized by similar characteristics. - `mediaObjects` `SKUGroupMediaObjectsConnection` **nullable** — Media objects stored under the SKU Group. - `metafields` `SKUGroupMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique human-friendly identifier for the group. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `options` `SKUGroupOptionsConnection` **nullable** — An option is a add-on that can be added on to a SKU group. - `priceRange` `PriceRange` **nullable** — The price range of the SKU group, showing min and max prices of SKUs in the group. - `references` `SKUGroupReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skuCount` `Int` **nullable** — The count of all SKUs associated with the SKU Group. Can be filtered by status. The default statuses are ACTIVE and DRAFT. - `skus` `SKUGroupSkusConnection` **nullable** — A SKU represents a stock keeping unit (SKU) in the catalog. - `status` `String!` **non-null** — The status of the SKU Group, one of `DRAFT`, `ACTIVE`, `ARCHIVED`. - `type` `String!` **non-null** — The type of the SKU Group, typically PHYSICAL or DIGITAL, but can also be a custom type. - `updatedAt` `DateTime!` **non-null** — The timestamp of when the SKU was updated. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the SKU group. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. - `shortLabel` `String` **nullable** deprecated — A short label for the group. Can be used instead of the label on smaller screens. Deprecated: Use channel-specific overrides for short labels. - `SKUs` `SKUGroupSKUsConnection` **nullable** deprecated — A SKU represents a stock keeping unit (SKU) in the catalog. Deprecated: Use skus instead. # archiveSku (https://developer.godaddy.com/en/docs/references/rest/catalog/sku/mutations/archiveSku) --- title: archiveSku description: Archive an existing SKU. full: true --- mutation Requires `commerce.product:write`. Archive an existing SKU. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** ## Possible returns * `SKU` `SKU` — A SKU represents a stock keeping unit (SKU) in the catalog. - `archivedAt` `DateTime` **nullable** — The timestamp of when the SKU was archived. - `attributes` `SKUAttributesConnection` **nullable** — Attributes are properties or characteristics of the SKU. For example, color or size. - `attributeValues` `SKUAttributeValuesConnection` **nullable** — Attribute values of SKU. - `backorderLimit` `Int` **nullable** — The number of backorders allowed for the SKU. If set to 0, backorders are not allowed. If set to null, backorders are allowed without limit. - `code` `String!` **non-null** — The unique code for the SKU. - `createdAt` `DateTime!` **non-null** — The timestamp of when the SKU was created. - `description` `String` **nullable** — The description of the SKU. - `disableInventoryTracking` `Boolean` **nullable** — Flag to mark whether stock should be tracked for the SKU. - `disablePriceOverrides` `Boolean` **nullable** — Flag to mark whether or not a custom price can be provided. - `disableShipping` `Boolean` **nullable** — Flag to mark whether the SKU should be shipped or not. - `eanCode` `String` **nullable** — The EAN code for the SKU. - `gtinCode` `String` **nullable** — The GTIN code for the SKU. - `htmlDescription` `String` **nullable** — HTML description for the SKU. Will be used to display rich text content to customers. - `id` `ID!` **non-null** — The globally-unique ID of the SKU. - `inventoryAdjustments` `SKUInventoryAdjustmentsConnection` **nullable** — An immutable entity that represents a change in state of a quantity of SKU at a particular time and location. Each adjustment will either have a positive, negative, or neutral impact on the count of available SKUs in a location. - `inventoryCounts` `SKUInventoryCountsConnection` **nullable** — The quantity of a SKU in a specific state at a particular time and location. - `isbnCode` `String` **nullable** — The ISBN code for the SKU. - `label` `String` **nullable** — The display label of the SKU. - `locations` `SKULocationsConnection` **nullable** — The locations where the SKU is available. - `mediaObjects` `SKUMediaObjectsConnection` **nullable** — Media stored under this SKU. - `metafields` `SKUMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique name for the SKU. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `prices` `SKUPricesConnection` **nullable** — These are all the prices the SKU can be sold at. The price can be different based the channel where it is listed or if there is a promotion running. - `references` `SKUReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skuGroup` `SKUGroup` **nullable** — A SKU group is a grouping of related SKUs. It provides information about all the SKUs that are sold together on storefronts or devices. - `status` `String` **nullable** — The status of the SKU, one of `DRAFT`, `ACTIVE`, `ARCHIVED`. - `unitCost` `SimpleMoney` **nullable** — The cost of the SKU per unit. This is a money object that includes the value and currency code. - `unitOfWeight` `String` **nullable** — The unit of weight, one of `KG`, `GR`, `LB`, `OZ`. - `upcCode` `String` **nullable** — The UPC code for the SKU. - `updatedAt` `DateTime!` **non-null** — The timestamp of when the SKU was updated. - `weight` `Float` **nullable** — The weight of the SKU. - `cost` `Int` **nullable** deprecated — DEPRECATED. Use unitCost instead. Deprecated: This cost field cannot specify currency code. Use `unitCost` instead. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the SKU. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. - `shortLabel` `String` **nullable** deprecated — A short label for the SKU, useful for UI with limited space. Deprecated: Use channel-specific overrides for short labels. - `SKUGroup` `SKUGroup` **nullable** deprecated — A SKU group is a grouping of related SKUs. It provides information about all the SKUs that are sold together on storefronts or devices. Deprecated: Use skuGroup instead. # archiveSkus (https://developer.godaddy.com/en/docs/references/rest/catalog/sku/mutations/archiveSkus) --- title: archiveSkus description: Archive multiple existing SKUs. Limit 25 SKUs. full: true --- mutation Requires `commerce.product:write`. Archive multiple existing SKUs. Limit 25 SKUs. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `ids` `[String!]!` **required** ## Possible returns * `SKU` `[SKU!]` — A SKU represents a stock keeping unit (SKU) in the catalog. - `archivedAt` `DateTime` **nullable** — The timestamp of when the SKU was archived. - `attributes` `SKUAttributesConnection` **nullable** — Attributes are properties or characteristics of the SKU. For example, color or size. - `attributeValues` `SKUAttributeValuesConnection` **nullable** — Attribute values of SKU. - `backorderLimit` `Int` **nullable** — The number of backorders allowed for the SKU. If set to 0, backorders are not allowed. If set to null, backorders are allowed without limit. - `code` `String!` **non-null** — The unique code for the SKU. - `createdAt` `DateTime!` **non-null** — The timestamp of when the SKU was created. - `description` `String` **nullable** — The description of the SKU. - `disableInventoryTracking` `Boolean` **nullable** — Flag to mark whether stock should be tracked for the SKU. - `disablePriceOverrides` `Boolean` **nullable** — Flag to mark whether or not a custom price can be provided. - `disableShipping` `Boolean` **nullable** — Flag to mark whether the SKU should be shipped or not. - `eanCode` `String` **nullable** — The EAN code for the SKU. - `gtinCode` `String` **nullable** — The GTIN code for the SKU. - `htmlDescription` `String` **nullable** — HTML description for the SKU. Will be used to display rich text content to customers. - `id` `ID!` **non-null** — The globally-unique ID of the SKU. - `inventoryAdjustments` `SKUInventoryAdjustmentsConnection` **nullable** — An immutable entity that represents a change in state of a quantity of SKU at a particular time and location. Each adjustment will either have a positive, negative, or neutral impact on the count of available SKUs in a location. - `inventoryCounts` `SKUInventoryCountsConnection` **nullable** — The quantity of a SKU in a specific state at a particular time and location. - `isbnCode` `String` **nullable** — The ISBN code for the SKU. - `label` `String` **nullable** — The display label of the SKU. - `locations` `SKULocationsConnection` **nullable** — The locations where the SKU is available. - `mediaObjects` `SKUMediaObjectsConnection` **nullable** — Media stored under this SKU. - `metafields` `SKUMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique name for the SKU. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `prices` `SKUPricesConnection` **nullable** — These are all the prices the SKU can be sold at. The price can be different based the channel where it is listed or if there is a promotion running. - `references` `SKUReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skuGroup` `SKUGroup` **nullable** — A SKU group is a grouping of related SKUs. It provides information about all the SKUs that are sold together on storefronts or devices. - `status` `String` **nullable** — The status of the SKU, one of `DRAFT`, `ACTIVE`, `ARCHIVED`. - `unitCost` `SimpleMoney` **nullable** — The cost of the SKU per unit. This is a money object that includes the value and currency code. - `unitOfWeight` `String` **nullable** — The unit of weight, one of `KG`, `GR`, `LB`, `OZ`. - `upcCode` `String` **nullable** — The UPC code for the SKU. - `updatedAt` `DateTime!` **non-null** — The timestamp of when the SKU was updated. - `weight` `Float` **nullable** — The weight of the SKU. - `cost` `Int` **nullable** deprecated — DEPRECATED. Use unitCost instead. Deprecated: This cost field cannot specify currency code. Use `unitCost` instead. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the SKU. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. - `shortLabel` `String` **nullable** deprecated — A short label for the SKU, useful for UI with limited space. Deprecated: Use channel-specific overrides for short labels. - `SKUGroup` `SKUGroup` **nullable** deprecated — A SKU group is a grouping of related SKUs. It provides information about all the SKUs that are sold together on storefronts or devices. Deprecated: Use skuGroup instead. # createSku (https://developer.godaddy.com/en/docs/references/rest/catalog/sku/mutations/createSku) --- title: createSku description: Create a new SKU. full: true --- mutation Requires `commerce.product:write`. Create a new SKU. For `SimpleMoneyInput.value`, send `1999` for $19.99 USD, not `19.99`. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `input` `CreateSKUInput!` **required** * `label` `String!` **required** * `attributeValueIds` `[String!]` **optional** * `attributeValues` `[AssociateAttributeValueToSKUInput!]` **optional** * `attributeName` `String!` **required** * `valueName` `String!` **required** * `backorderLimit` `Int` **optional** * `code` `String` **optional** * `cost` `Int` **optional** — DEPRECATED. Use unitCost instead. Deprecated: This cost field cannot specify currency code. Use `unitCost` instead. * `description` `String` **optional** * `disableInventoryTracking` `Boolean` **optional** * `disablePriceOverrides` `Boolean` **optional** * `disableShipping` `Boolean` **optional** * `eanCode` `String` **optional** * `gtinCode` `String` **optional** * `htmlDescription` `String` **optional** * `HTMLDescription` `String` **optional** — Deprecated: Use htmlDescription instead. * `inventoryQuantities` `[CreateSKUInventoryInput!]` **optional** * `locationId` `String!` **required** * `quantity` `Int!` **required** * `isbnCode` `String` **optional** * `mediaObjects` `[CreateMediaObjectInput!]` **optional** * `type` `String!` **required** — The type of the media, one of `IMAGE`, `VIDEO`, `AUDIO`. * `url` `String!` **required** * `label` `String` **optional** * `metafields` `[CreateMetafieldInput!]` **optional** * `key` `String!` **required** * `namespace` `String!` **required** * `type` `String!` **required** — Metafield value type. Live catalog validation accepts lowercase values such as `boolean`, `string`, `stringMultiLine`, `number`, `numberDecimal`, `date`, `dateTime`, `json`, `measurement`, `url`, `reference`, `money`, `list.string`, `list.number`, `list.numberDecimal`. Uppercase `STRING` is rejected. * `value` `String!` **required** * `name` `String` **optional** — Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). * `position` `Int` **optional** * `metafields` `[CreateMetafieldInput!]` **optional** * `key` `String!` **required** * `namespace` `String!` **required** * `type` `String!` **required** — Metafield value type. Live catalog validation accepts lowercase values such as `boolean`, `string`, `stringMultiLine`, `number`, `numberDecimal`, `date`, `dateTime`, `json`, `measurement`, `url`, `reference`, `money`, `list.string`, `list.number`, `list.numberDecimal`. Uppercase `STRING` is rejected. * `value` `String!` **required** * `name` `String` **optional** — Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). * `prices` `[CreateSKUPriceInput!]` **optional** * `value` `SimpleMoneyInput!` **required** * `currencyCode` `String!` **required** * `value` `Float!` **required** — Integer minor units in the smallest currency unit (for USD, cents: `1999` = $19.99). Send `1999`, not `19.99`. * `compareAtValue` `SimpleMoneyInput` **optional** * `currencyCode` `String!` **required** * `value` `Float!` **required** — Integer minor units in the smallest currency unit (for USD, cents: `1999` = $19.99). Send `1999`, not `19.99`. * `references` `[CreateReferenceInput!]` **optional** * `origin` `String!` **required** * `value` `String!` **required** * `shortLabel` `String` **optional** * `skuGroupId` `String` **optional** * `status` `String` **optional** — The status of the SKU, one of `DRAFT`, `ACTIVE`, `ARCHIVED`. * `unitCost` `SimpleMoneyInput` **optional** * `currencyCode` `String!` **required** * `value` `Float!` **required** — Integer minor units in the smallest currency unit (for USD, cents: `1999` = $19.99). Send `1999`, not `19.99`. * `unitOfWeight` `String` **optional** — The status of the SKU, one of `KG`, `GR`, `LB`, `OZ`. * `upcCode` `String` **optional** * `weight` `Float` **optional** ## Possible returns * `SKU` `SKU` — A SKU represents a stock keeping unit (SKU) in the catalog. - `archivedAt` `DateTime` **nullable** — The timestamp of when the SKU was archived. - `attributes` `SKUAttributesConnection` **nullable** — Attributes are properties or characteristics of the SKU. For example, color or size. - `attributeValues` `SKUAttributeValuesConnection` **nullable** — Attribute values of SKU. - `backorderLimit` `Int` **nullable** — The number of backorders allowed for the SKU. If set to 0, backorders are not allowed. If set to null, backorders are allowed without limit. - `code` `String!` **non-null** — The unique code for the SKU. - `createdAt` `DateTime!` **non-null** — The timestamp of when the SKU was created. - `description` `String` **nullable** — The description of the SKU. - `disableInventoryTracking` `Boolean` **nullable** — Flag to mark whether stock should be tracked for the SKU. - `disablePriceOverrides` `Boolean` **nullable** — Flag to mark whether or not a custom price can be provided. - `disableShipping` `Boolean` **nullable** — Flag to mark whether the SKU should be shipped or not. - `eanCode` `String` **nullable** — The EAN code for the SKU. - `gtinCode` `String` **nullable** — The GTIN code for the SKU. - `htmlDescription` `String` **nullable** — HTML description for the SKU. Will be used to display rich text content to customers. - `id` `ID!` **non-null** — The globally-unique ID of the SKU. - `inventoryAdjustments` `SKUInventoryAdjustmentsConnection` **nullable** — An immutable entity that represents a change in state of a quantity of SKU at a particular time and location. Each adjustment will either have a positive, negative, or neutral impact on the count of available SKUs in a location. - `inventoryCounts` `SKUInventoryCountsConnection` **nullable** — The quantity of a SKU in a specific state at a particular time and location. - `isbnCode` `String` **nullable** — The ISBN code for the SKU. - `label` `String` **nullable** — The display label of the SKU. - `locations` `SKULocationsConnection` **nullable** — The locations where the SKU is available. - `mediaObjects` `SKUMediaObjectsConnection` **nullable** — Media stored under this SKU. - `metafields` `SKUMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique name for the SKU. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `prices` `SKUPricesConnection` **nullable** — These are all the prices the SKU can be sold at. The price can be different based the channel where it is listed or if there is a promotion running. - `references` `SKUReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skuGroup` `SKUGroup` **nullable** — A SKU group is a grouping of related SKUs. It provides information about all the SKUs that are sold together on storefronts or devices. - `status` `String` **nullable** — The status of the SKU, one of `DRAFT`, `ACTIVE`, `ARCHIVED`. - `unitCost` `SimpleMoney` **nullable** — The cost of the SKU per unit. This is a money object that includes the value and currency code. - `unitOfWeight` `String` **nullable** — The unit of weight, one of `KG`, `GR`, `LB`, `OZ`. - `upcCode` `String` **nullable** — The UPC code for the SKU. - `updatedAt` `DateTime!` **non-null** — The timestamp of when the SKU was updated. - `weight` `Float` **nullable** — The weight of the SKU. - `cost` `Int` **nullable** deprecated — DEPRECATED. Use unitCost instead. Deprecated: This cost field cannot specify currency code. Use `unitCost` instead. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the SKU. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. - `shortLabel` `String` **nullable** deprecated — A short label for the SKU, useful for UI with limited space. Deprecated: Use channel-specific overrides for short labels. - `SKUGroup` `SKUGroup` **nullable** deprecated — A SKU group is a grouping of related SKUs. It provides information about all the SKUs that are sold together on storefronts or devices. Deprecated: Use skuGroup instead. # createSkuPrice (https://developer.godaddy.com/en/docs/references/rest/catalog/sku/mutations/createSkuPrice) --- title: createSkuPrice description: Create a price. full: true --- mutation Requires `commerce.product:write`. Create a price. Use `MutationCreateSkuPriceInput` (it includes `skuId`). Nested `CreateSKUPriceInput` on `createSku` has no `skuId`. For `SimpleMoneyInput.value`, send `1999` for $19.99 USD, not `19.99`. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `input` `MutationCreateSkuPriceInput!` **required** * `skuId` `ID!` **required** * `value` `SimpleMoneyInput!` **required** * `currencyCode` `String!` **required** * `value` `Float!` **required** — Integer minor units in the smallest currency unit (for USD, cents: `1999` = $19.99). Send `1999`, not `19.99`. * `compareAtValue` `SimpleMoneyInput` **optional** * `currencyCode` `String!` **required** * `value` `Float!` **required** — Integer minor units in the smallest currency unit (for USD, cents: `1999` = $19.99). Send `1999`, not `19.99`. ## Possible returns * `SKUPrice` `SKUPrice` — Represents the cost of a SKU - `compareAtValue` `SimpleMoney` **nullable** — The compare-at value of the price. - `createdAt` `DateTime!` **non-null** — The timestamp of when the price was created. - `id` `ID!` **non-null** — The globally-unique ID of the price. - `sku` `SKU` **nullable** — A SKU represents a stock keeping unit (SKU) in the catalog. - `updatedAt` `DateTime!` **non-null** — The last update timestamp of the price. - `value` `SimpleMoney!` **non-null** — The value of the price. - `SKU` `SKU` **nullable** deprecated — A SKU represents a stock keeping unit (SKU) in the catalog. Deprecated: Use sku instead. # createSkus (https://developer.godaddy.com/en/docs/references/rest/catalog/sku/mutations/createSkus) --- title: createSkus description: Create multiple new SKUs in a single transaction. Limit 25 SKUs. full: true --- mutation Requires `commerce.product:write`. Create multiple new SKUs in a single transaction. Limit 25 SKUs. The `input` array accepts a maximum of 25 items per call. To create more than 25 SKUs, split them into multiple requests. For `SimpleMoneyInput.value`, send `1999` for $19.99 USD, not `19.99`. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `input` `[CreateSKUInput!]!` **required** * `label` `String!` **required** * `attributeValueIds` `[String!]` **optional** * `attributeValues` `[AssociateAttributeValueToSKUInput!]` **optional** * `attributeName` `String!` **required** * `valueName` `String!` **required** * `backorderLimit` `Int` **optional** * `code` `String` **optional** * `cost` `Int` **optional** — DEPRECATED. Use unitCost instead. Deprecated: This cost field cannot specify currency code. Use `unitCost` instead. * `description` `String` **optional** * `disableInventoryTracking` `Boolean` **optional** * `disablePriceOverrides` `Boolean` **optional** * `disableShipping` `Boolean` **optional** * `eanCode` `String` **optional** * `gtinCode` `String` **optional** * `htmlDescription` `String` **optional** * `HTMLDescription` `String` **optional** — Deprecated: Use htmlDescription instead. * `inventoryQuantities` `[CreateSKUInventoryInput!]` **optional** * `locationId` `String!` **required** * `quantity` `Int!` **required** * `isbnCode` `String` **optional** * `mediaObjects` `[CreateMediaObjectInput!]` **optional** * `type` `String!` **required** — The type of the media, one of `IMAGE`, `VIDEO`, `AUDIO`. * `url` `String!` **required** * `label` `String` **optional** * `metafields` `[CreateMetafieldInput!]` **optional** * `key` `String!` **required** * `namespace` `String!` **required** * `type` `String!` **required** — Metafield value type. Live catalog validation accepts lowercase values such as `boolean`, `string`, `stringMultiLine`, `number`, `numberDecimal`, `date`, `dateTime`, `json`, `measurement`, `url`, `reference`, `money`, `list.string`, `list.number`, `list.numberDecimal`. Uppercase `STRING` is rejected. * `value` `String!` **required** * `name` `String` **optional** — Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). * `position` `Int` **optional** * `metafields` `[CreateMetafieldInput!]` **optional** * `key` `String!` **required** * `namespace` `String!` **required** * `type` `String!` **required** — Metafield value type. Live catalog validation accepts lowercase values such as `boolean`, `string`, `stringMultiLine`, `number`, `numberDecimal`, `date`, `dateTime`, `json`, `measurement`, `url`, `reference`, `money`, `list.string`, `list.number`, `list.numberDecimal`. Uppercase `STRING` is rejected. * `value` `String!` **required** * `name` `String` **optional** — Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). * `prices` `[CreateSKUPriceInput!]` **optional** * `value` `SimpleMoneyInput!` **required** * `currencyCode` `String!` **required** * `value` `Float!` **required** — Integer minor units in the smallest currency unit (for USD, cents: `1999` = $19.99). Send `1999`, not `19.99`. * `compareAtValue` `SimpleMoneyInput` **optional** * `currencyCode` `String!` **required** * `value` `Float!` **required** — Integer minor units in the smallest currency unit (for USD, cents: `1999` = $19.99). Send `1999`, not `19.99`. * `references` `[CreateReferenceInput!]` **optional** * `origin` `String!` **required** * `value` `String!` **required** * `shortLabel` `String` **optional** * `skuGroupId` `String` **optional** * `status` `String` **optional** — The status of the SKU, one of `DRAFT`, `ACTIVE`, `ARCHIVED`. * `unitCost` `SimpleMoneyInput` **optional** * `currencyCode` `String!` **required** * `value` `Float!` **required** — Integer minor units in the smallest currency unit (for USD, cents: `1999` = $19.99). Send `1999`, not `19.99`. * `unitOfWeight` `String` **optional** — The status of the SKU, one of `KG`, `GR`, `LB`, `OZ`. * `upcCode` `String` **optional** * `weight` `Float` **optional** ## Possible returns * `SKU` `[SKU!]` — A SKU represents a stock keeping unit (SKU) in the catalog. - `archivedAt` `DateTime` **nullable** — The timestamp of when the SKU was archived. - `attributes` `SKUAttributesConnection` **nullable** — Attributes are properties or characteristics of the SKU. For example, color or size. - `attributeValues` `SKUAttributeValuesConnection` **nullable** — Attribute values of SKU. - `backorderLimit` `Int` **nullable** — The number of backorders allowed for the SKU. If set to 0, backorders are not allowed. If set to null, backorders are allowed without limit. - `code` `String!` **non-null** — The unique code for the SKU. - `createdAt` `DateTime!` **non-null** — The timestamp of when the SKU was created. - `description` `String` **nullable** — The description of the SKU. - `disableInventoryTracking` `Boolean` **nullable** — Flag to mark whether stock should be tracked for the SKU. - `disablePriceOverrides` `Boolean` **nullable** — Flag to mark whether or not a custom price can be provided. - `disableShipping` `Boolean` **nullable** — Flag to mark whether the SKU should be shipped or not. - `eanCode` `String` **nullable** — The EAN code for the SKU. - `gtinCode` `String` **nullable** — The GTIN code for the SKU. - `htmlDescription` `String` **nullable** — HTML description for the SKU. Will be used to display rich text content to customers. - `id` `ID!` **non-null** — The globally-unique ID of the SKU. - `inventoryAdjustments` `SKUInventoryAdjustmentsConnection` **nullable** — An immutable entity that represents a change in state of a quantity of SKU at a particular time and location. Each adjustment will either have a positive, negative, or neutral impact on the count of available SKUs in a location. - `inventoryCounts` `SKUInventoryCountsConnection` **nullable** — The quantity of a SKU in a specific state at a particular time and location. - `isbnCode` `String` **nullable** — The ISBN code for the SKU. - `label` `String` **nullable** — The display label of the SKU. - `locations` `SKULocationsConnection` **nullable** — The locations where the SKU is available. - `mediaObjects` `SKUMediaObjectsConnection` **nullable** — Media stored under this SKU. - `metafields` `SKUMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique name for the SKU. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `prices` `SKUPricesConnection` **nullable** — These are all the prices the SKU can be sold at. The price can be different based the channel where it is listed or if there is a promotion running. - `references` `SKUReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skuGroup` `SKUGroup` **nullable** — A SKU group is a grouping of related SKUs. It provides information about all the SKUs that are sold together on storefronts or devices. - `status` `String` **nullable** — The status of the SKU, one of `DRAFT`, `ACTIVE`, `ARCHIVED`. - `unitCost` `SimpleMoney` **nullable** — The cost of the SKU per unit. This is a money object that includes the value and currency code. - `unitOfWeight` `String` **nullable** — The unit of weight, one of `KG`, `GR`, `LB`, `OZ`. - `upcCode` `String` **nullable** — The UPC code for the SKU. - `updatedAt` `DateTime!` **non-null** — The timestamp of when the SKU was updated. - `weight` `Float` **nullable** — The weight of the SKU. - `cost` `Int` **nullable** deprecated — DEPRECATED. Use unitCost instead. Deprecated: This cost field cannot specify currency code. Use `unitCost` instead. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the SKU. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. - `shortLabel` `String` **nullable** deprecated — A short label for the SKU, useful for UI with limited space. Deprecated: Use channel-specific overrides for short labels. - `SKUGroup` `SKUGroup` **nullable** deprecated — A SKU group is a grouping of related SKUs. It provides information about all the SKUs that are sold together on storefronts or devices. Deprecated: Use skuGroup instead. # removeMetafieldsFromSku (https://developer.godaddy.com/en/docs/references/rest/catalog/sku/mutations/removeMetafieldsFromSku) --- title: removeMetafieldsFromSku description: Remove metafields from an existing SKU. full: true --- mutation Requires `commerce.product:write`. Remove metafields from an existing SKU. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationRemoveMetafieldsFromSkuInput!` **required** * `metafields` `[RemoveMetafieldInput!]!` **required** * `key` `String!` **required** * `namespace` `String!` **required** ## Possible returns * `SKU` `SKU` — A SKU represents a stock keeping unit (SKU) in the catalog. - `archivedAt` `DateTime` **nullable** — The timestamp of when the SKU was archived. - `attributes` `SKUAttributesConnection` **nullable** — Attributes are properties or characteristics of the SKU. For example, color or size. - `attributeValues` `SKUAttributeValuesConnection` **nullable** — Attribute values of SKU. - `backorderLimit` `Int` **nullable** — The number of backorders allowed for the SKU. If set to 0, backorders are not allowed. If set to null, backorders are allowed without limit. - `code` `String!` **non-null** — The unique code for the SKU. - `createdAt` `DateTime!` **non-null** — The timestamp of when the SKU was created. - `description` `String` **nullable** — The description of the SKU. - `disableInventoryTracking` `Boolean` **nullable** — Flag to mark whether stock should be tracked for the SKU. - `disablePriceOverrides` `Boolean` **nullable** — Flag to mark whether or not a custom price can be provided. - `disableShipping` `Boolean` **nullable** — Flag to mark whether the SKU should be shipped or not. - `eanCode` `String` **nullable** — The EAN code for the SKU. - `gtinCode` `String` **nullable** — The GTIN code for the SKU. - `htmlDescription` `String` **nullable** — HTML description for the SKU. Will be used to display rich text content to customers. - `id` `ID!` **non-null** — The globally-unique ID of the SKU. - `inventoryAdjustments` `SKUInventoryAdjustmentsConnection` **nullable** — An immutable entity that represents a change in state of a quantity of SKU at a particular time and location. Each adjustment will either have a positive, negative, or neutral impact on the count of available SKUs in a location. - `inventoryCounts` `SKUInventoryCountsConnection` **nullable** — The quantity of a SKU in a specific state at a particular time and location. - `isbnCode` `String` **nullable** — The ISBN code for the SKU. - `label` `String` **nullable** — The display label of the SKU. - `locations` `SKULocationsConnection` **nullable** — The locations where the SKU is available. - `mediaObjects` `SKUMediaObjectsConnection` **nullable** — Media stored under this SKU. - `metafields` `SKUMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique name for the SKU. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `prices` `SKUPricesConnection` **nullable** — These are all the prices the SKU can be sold at. The price can be different based the channel where it is listed or if there is a promotion running. - `references` `SKUReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skuGroup` `SKUGroup` **nullable** — A SKU group is a grouping of related SKUs. It provides information about all the SKUs that are sold together on storefronts or devices. - `status` `String` **nullable** — The status of the SKU, one of `DRAFT`, `ACTIVE`, `ARCHIVED`. - `unitCost` `SimpleMoney` **nullable** — The cost of the SKU per unit. This is a money object that includes the value and currency code. - `unitOfWeight` `String` **nullable** — The unit of weight, one of `KG`, `GR`, `LB`, `OZ`. - `upcCode` `String` **nullable** — The UPC code for the SKU. - `updatedAt` `DateTime!` **non-null** — The timestamp of when the SKU was updated. - `weight` `Float` **nullable** — The weight of the SKU. - `cost` `Int` **nullable** deprecated — DEPRECATED. Use unitCost instead. Deprecated: This cost field cannot specify currency code. Use `unitCost` instead. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the SKU. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. - `shortLabel` `String` **nullable** deprecated — A short label for the SKU, useful for UI with limited space. Deprecated: Use channel-specific overrides for short labels. - `SKUGroup` `SKUGroup` **nullable** deprecated — A SKU group is a grouping of related SKUs. It provides information about all the SKUs that are sold together on storefronts or devices. Deprecated: Use skuGroup instead. # removePricesFromSku (https://developer.godaddy.com/en/docs/references/rest/catalog/sku/mutations/removePricesFromSku) --- title: removePricesFromSku description: Remove prices from an existing SKU. full: true --- mutation Requires `commerce.product:write`. Remove prices from an existing SKU. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationRemovePricesFromSkuInput!` **required** * `priceIds` `[String!]!` **required** ## Possible returns * `SKU` `SKU` — A SKU represents a stock keeping unit (SKU) in the catalog. - `archivedAt` `DateTime` **nullable** — The timestamp of when the SKU was archived. - `attributes` `SKUAttributesConnection` **nullable** — Attributes are properties or characteristics of the SKU. For example, color or size. - `attributeValues` `SKUAttributeValuesConnection` **nullable** — Attribute values of SKU. - `backorderLimit` `Int` **nullable** — The number of backorders allowed for the SKU. If set to 0, backorders are not allowed. If set to null, backorders are allowed without limit. - `code` `String!` **non-null** — The unique code for the SKU. - `createdAt` `DateTime!` **non-null** — The timestamp of when the SKU was created. - `description` `String` **nullable** — The description of the SKU. - `disableInventoryTracking` `Boolean` **nullable** — Flag to mark whether stock should be tracked for the SKU. - `disablePriceOverrides` `Boolean` **nullable** — Flag to mark whether or not a custom price can be provided. - `disableShipping` `Boolean` **nullable** — Flag to mark whether the SKU should be shipped or not. - `eanCode` `String` **nullable** — The EAN code for the SKU. - `gtinCode` `String` **nullable** — The GTIN code for the SKU. - `htmlDescription` `String` **nullable** — HTML description for the SKU. Will be used to display rich text content to customers. - `id` `ID!` **non-null** — The globally-unique ID of the SKU. - `inventoryAdjustments` `SKUInventoryAdjustmentsConnection` **nullable** — An immutable entity that represents a change in state of a quantity of SKU at a particular time and location. Each adjustment will either have a positive, negative, or neutral impact on the count of available SKUs in a location. - `inventoryCounts` `SKUInventoryCountsConnection` **nullable** — The quantity of a SKU in a specific state at a particular time and location. - `isbnCode` `String` **nullable** — The ISBN code for the SKU. - `label` `String` **nullable** — The display label of the SKU. - `locations` `SKULocationsConnection` **nullable** — The locations where the SKU is available. - `mediaObjects` `SKUMediaObjectsConnection` **nullable** — Media stored under this SKU. - `metafields` `SKUMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique name for the SKU. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `prices` `SKUPricesConnection` **nullable** — These are all the prices the SKU can be sold at. The price can be different based the channel where it is listed or if there is a promotion running. - `references` `SKUReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skuGroup` `SKUGroup` **nullable** — A SKU group is a grouping of related SKUs. It provides information about all the SKUs that are sold together on storefronts or devices. - `status` `String` **nullable** — The status of the SKU, one of `DRAFT`, `ACTIVE`, `ARCHIVED`. - `unitCost` `SimpleMoney` **nullable** — The cost of the SKU per unit. This is a money object that includes the value and currency code. - `unitOfWeight` `String` **nullable** — The unit of weight, one of `KG`, `GR`, `LB`, `OZ`. - `upcCode` `String` **nullable** — The UPC code for the SKU. - `updatedAt` `DateTime!` **non-null** — The timestamp of when the SKU was updated. - `weight` `Float` **nullable** — The weight of the SKU. - `cost` `Int` **nullable** deprecated — DEPRECATED. Use unitCost instead. Deprecated: This cost field cannot specify currency code. Use `unitCost` instead. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the SKU. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. - `shortLabel` `String` **nullable** deprecated — A short label for the SKU, useful for UI with limited space. Deprecated: Use channel-specific overrides for short labels. - `SKUGroup` `SKUGroup` **nullable** deprecated — A SKU group is a grouping of related SKUs. It provides information about all the SKUs that are sold together on storefronts or devices. Deprecated: Use skuGroup instead. # updateSku (https://developer.godaddy.com/en/docs/references/rest/catalog/sku/mutations/updateSku) --- title: updateSku description: Update an existing SKU. full: true --- mutation Requires `commerce.product:write`. Update an existing SKU. `status` must be `DRAFT`, `ACTIVE`, or `ARCHIVED`. For `SimpleMoneyInput.value`, send `1999` for $19.99 USD, not `19.99`. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationUpdateSkuInput!` **required** * `backorderLimit` `Int` **optional** * `code` `String` **optional** * `cost` `Int` **optional** — DEPRECATED. Use unitCost instead. Deprecated: This cost field cannot specify currency code. Use `unitCost` instead. * `description` `String` **optional** * `disableInventoryTracking` `Boolean` **optional** * `disablePriceOverrides` `Boolean` **optional** * `disableShipping` `Boolean` **optional** * `eanCode` `String` **optional** * `gtinCode` `String` **optional** * `htmlDescription` `String` **optional** * `HTMLDescription` `String` **optional** — Deprecated: Use htmlDescription instead. * `isbnCode` `String` **optional** * `label` `String` **optional** * `metafields` `[UpsertMetafieldInput!]` **optional** * `key` `String!` **required** * `namespace` `String!` **required** * `type` `String!` **required** * `value` `String!` **required** * `name` `String` **optional** — Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). * `shortLabel` `String` **optional** — Deprecated: Use channel-specific overrides for short labels. * `status` `String` **optional** — The status of the SKU, one of `DRAFT`, `ACTIVE`, `ARCHIVED`. * `unitCost` `SimpleMoneyInput` **optional** * `currencyCode` `String!` **required** * `value` `Float!` **required** — Integer minor units in the smallest currency unit (for USD, cents: `1999` = $19.99). Send `1999`, not `19.99`. * `unitOfWeight` `String` **optional** — The unit of weight, one of `KG`, `GR`, `LB`, `OZ`. * `upcCode` `String` **optional** * `weight` `Float` **optional** ## Possible returns * `SKU` `SKU` — A SKU represents a stock keeping unit (SKU) in the catalog. - `archivedAt` `DateTime` **nullable** — The timestamp of when the SKU was archived. - `attributes` `SKUAttributesConnection` **nullable** — Attributes are properties or characteristics of the SKU. For example, color or size. - `attributeValues` `SKUAttributeValuesConnection` **nullable** — Attribute values of SKU. - `backorderLimit` `Int` **nullable** — The number of backorders allowed for the SKU. If set to 0, backorders are not allowed. If set to null, backorders are allowed without limit. - `code` `String!` **non-null** — The unique code for the SKU. - `createdAt` `DateTime!` **non-null** — The timestamp of when the SKU was created. - `description` `String` **nullable** — The description of the SKU. - `disableInventoryTracking` `Boolean` **nullable** — Flag to mark whether stock should be tracked for the SKU. - `disablePriceOverrides` `Boolean` **nullable** — Flag to mark whether or not a custom price can be provided. - `disableShipping` `Boolean` **nullable** — Flag to mark whether the SKU should be shipped or not. - `eanCode` `String` **nullable** — The EAN code for the SKU. - `gtinCode` `String` **nullable** — The GTIN code for the SKU. - `htmlDescription` `String` **nullable** — HTML description for the SKU. Will be used to display rich text content to customers. - `id` `ID!` **non-null** — The globally-unique ID of the SKU. - `inventoryAdjustments` `SKUInventoryAdjustmentsConnection` **nullable** — An immutable entity that represents a change in state of a quantity of SKU at a particular time and location. Each adjustment will either have a positive, negative, or neutral impact on the count of available SKUs in a location. - `inventoryCounts` `SKUInventoryCountsConnection` **nullable** — The quantity of a SKU in a specific state at a particular time and location. - `isbnCode` `String` **nullable** — The ISBN code for the SKU. - `label` `String` **nullable** — The display label of the SKU. - `locations` `SKULocationsConnection` **nullable** — The locations where the SKU is available. - `mediaObjects` `SKUMediaObjectsConnection` **nullable** — Media stored under this SKU. - `metafields` `SKUMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique name for the SKU. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `prices` `SKUPricesConnection` **nullable** — These are all the prices the SKU can be sold at. The price can be different based the channel where it is listed or if there is a promotion running. - `references` `SKUReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skuGroup` `SKUGroup` **nullable** — A SKU group is a grouping of related SKUs. It provides information about all the SKUs that are sold together on storefronts or devices. - `status` `String` **nullable** — The status of the SKU, one of `DRAFT`, `ACTIVE`, `ARCHIVED`. - `unitCost` `SimpleMoney` **nullable** — The cost of the SKU per unit. This is a money object that includes the value and currency code. - `unitOfWeight` `String` **nullable** — The unit of weight, one of `KG`, `GR`, `LB`, `OZ`. - `upcCode` `String` **nullable** — The UPC code for the SKU. - `updatedAt` `DateTime!` **non-null** — The timestamp of when the SKU was updated. - `weight` `Float` **nullable** — The weight of the SKU. - `cost` `Int` **nullable** deprecated — DEPRECATED. Use unitCost instead. Deprecated: This cost field cannot specify currency code. Use `unitCost` instead. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the SKU. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. - `shortLabel` `String` **nullable** deprecated — A short label for the SKU, useful for UI with limited space. Deprecated: Use channel-specific overrides for short labels. - `SKUGroup` `SKUGroup` **nullable** deprecated — A SKU group is a grouping of related SKUs. It provides information about all the SKUs that are sold together on storefronts or devices. Deprecated: Use skuGroup instead. # updateSkuPrice (https://developer.godaddy.com/en/docs/references/rest/catalog/sku/mutations/updateSkuPrice) --- title: updateSkuPrice description: Update an existing price object. full: true --- mutation Requires `commerce.product:write`. Update an existing price object. For `SimpleMoneyInput.value`, send `1999` for $19.99 USD, not `19.99`. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationUpdateSkuPriceInput!` **required** * `compareAtValue` `SimpleMoneyInput` **optional** * `currencyCode` `String!` **required** * `value` `Float!` **required** — Integer minor units in the smallest currency unit (for USD, cents: `1999` = $19.99). Send `1999`, not `19.99`. * `value` `SimpleMoneyInput` **optional** * `currencyCode` `String!` **required** * `value` `Float!` **required** — Integer minor units in the smallest currency unit (for USD, cents: `1999` = $19.99). Send `1999`, not `19.99`. ## Possible returns * `SKUPrice` `SKUPrice` — Represents the cost of a SKU - `compareAtValue` `SimpleMoney` **nullable** — The compare-at value of the price. - `createdAt` `DateTime!` **non-null** — The timestamp of when the price was created. - `id` `ID!` **non-null** — The globally-unique ID of the price. - `sku` `SKU` **nullable** — A SKU represents a stock keeping unit (SKU) in the catalog. - `updatedAt` `DateTime!` **non-null** — The last update timestamp of the price. - `value` `SimpleMoney!` **non-null** — The value of the price. - `SKU` `SKU` **nullable** deprecated — A SKU represents a stock keeping unit (SKU) in the catalog. Deprecated: Use sku instead. # updateSkuPriceCurrencyCode (https://developer.godaddy.com/en/docs/references/rest/catalog/sku/mutations/updateSkuPriceCurrencyCode) --- title: updateSkuPriceCurrencyCode description: >- Update the currency code for an existing price. This updates the currency code for both value and compareAtValue. full: true --- mutation Requires `commerce.product:write`. Update the currency code for an existing price. This updates the currency code for both value and compareAtValue. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationUpdateSkuPriceCurrencyCodeInput!` **required** * `currencyCode` `String!` **required** ## Possible returns * `SKUPrice` `SKUPrice` — Represents the cost of a SKU - `compareAtValue` `SimpleMoney` **nullable** — The compare-at value of the price. - `createdAt` `DateTime!` **non-null** — The timestamp of when the price was created. - `id` `ID!` **non-null** — The globally-unique ID of the price. - `sku` `SKU` **nullable** — A SKU represents a stock keeping unit (SKU) in the catalog. - `updatedAt` `DateTime!` **non-null** — The last update timestamp of the price. - `value` `SimpleMoney!` **non-null** — The value of the price. - `SKU` `SKU` **nullable** deprecated — A SKU represents a stock keeping unit (SKU) in the catalog. Deprecated: Use sku instead. # sku (https://developer.godaddy.com/en/docs/references/rest/catalog/sku/queries/sku) --- title: sku description: Query `sku` on the catalog subgraph (SKU). full: true --- query Requires `commerce.product:read`. Query `sku` on the catalog subgraph (SKU). ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** ## Possible returns * `SKU` `SKU` — A SKU represents a stock keeping unit (SKU) in the catalog. - `archivedAt` `DateTime` **nullable** — The timestamp of when the SKU was archived. - `attributes` `SKUAttributesConnection` **nullable** — Attributes are properties or characteristics of the SKU. For example, color or size. - `attributeValues` `SKUAttributeValuesConnection` **nullable** — Attribute values of SKU. - `backorderLimit` `Int` **nullable** — The number of backorders allowed for the SKU. If set to 0, backorders are not allowed. If set to null, backorders are allowed without limit. - `code` `String!` **non-null** — The unique code for the SKU. - `createdAt` `DateTime!` **non-null** — The timestamp of when the SKU was created. - `description` `String` **nullable** — The description of the SKU. - `disableInventoryTracking` `Boolean` **nullable** — Flag to mark whether stock should be tracked for the SKU. - `disablePriceOverrides` `Boolean` **nullable** — Flag to mark whether or not a custom price can be provided. - `disableShipping` `Boolean` **nullable** — Flag to mark whether the SKU should be shipped or not. - `eanCode` `String` **nullable** — The EAN code for the SKU. - `gtinCode` `String` **nullable** — The GTIN code for the SKU. - `htmlDescription` `String` **nullable** — HTML description for the SKU. Will be used to display rich text content to customers. - `id` `ID!` **non-null** — The globally-unique ID of the SKU. - `inventoryAdjustments` `SKUInventoryAdjustmentsConnection` **nullable** — An immutable entity that represents a change in state of a quantity of SKU at a particular time and location. Each adjustment will either have a positive, negative, or neutral impact on the count of available SKUs in a location. - `inventoryCounts` `SKUInventoryCountsConnection` **nullable** — The quantity of a SKU in a specific state at a particular time and location. - `isbnCode` `String` **nullable** — The ISBN code for the SKU. - `label` `String` **nullable** — The display label of the SKU. - `locations` `SKULocationsConnection` **nullable** — The locations where the SKU is available. - `mediaObjects` `SKUMediaObjectsConnection` **nullable** — Media stored under this SKU. - `metafields` `SKUMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique name for the SKU. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `prices` `SKUPricesConnection` **nullable** — These are all the prices the SKU can be sold at. The price can be different based the channel where it is listed or if there is a promotion running. - `references` `SKUReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skuGroup` `SKUGroup` **nullable** — A SKU group is a grouping of related SKUs. It provides information about all the SKUs that are sold together on storefronts or devices. - `status` `String` **nullable** — The status of the SKU, one of `DRAFT`, `ACTIVE`, `ARCHIVED`. - `unitCost` `SimpleMoney` **nullable** — The cost of the SKU per unit. This is a money object that includes the value and currency code. - `unitOfWeight` `String` **nullable** — The unit of weight, one of `KG`, `GR`, `LB`, `OZ`. - `upcCode` `String` **nullable** — The UPC code for the SKU. - `updatedAt` `DateTime!` **non-null** — The timestamp of when the SKU was updated. - `weight` `Float` **nullable** — The weight of the SKU. - `cost` `Int` **nullable** deprecated — DEPRECATED. Use unitCost instead. Deprecated: This cost field cannot specify currency code. Use `unitCost` instead. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the SKU. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. - `shortLabel` `String` **nullable** deprecated — A short label for the SKU, useful for UI with limited space. Deprecated: Use channel-specific overrides for short labels. - `SKUGroup` `SKUGroup` **nullable** deprecated — A SKU group is a grouping of related SKUs. It provides information about all the SKUs that are sold together on storefronts or devices. Deprecated: Use skuGroup instead. # skuPrices (https://developer.godaddy.com/en/docs/references/rest/catalog/sku/queries/skuPrices) --- title: skuPrices description: Query all SKU prices. full: true --- query Requires `commerce.product:read`. Query all SKU prices. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `after` `String` **optional** * `before` `String` **optional** * `currencyCode` `CurrencyCodeFilter` **optional** — Filter prices by currency code. * `eq` `String` **optional** — Filters items where the currency code equals the specified 3-letter ISO currency code. * `in` `[String!]` **optional** — Filters items where the currency code matches any of the specified 3-letter ISO currency codes. * `first` `Int` **optional** * `id` `SKUPriceIdsFilter` **optional** * `in` `[String!]` **optional** * `last` `Int` **optional** * `orderBy` `SKUPriceOrderBy` **optional** * `id` `OrderByDirectionEnum` **optional** * `updatedAt` `OrderByDirectionEnum` **optional** * `paginationType` `PaginationType` **optional** Default: `"CURSOR"`. * `skuId` `SKUIdFilter` **optional** * `eq` `String` **optional** * `in` `[String!]` **optional** * `skuStatus` `SKUStatusFilter` **optional** — Filter prices by the status of the parent SKU (ACTIVE, DRAFT, ARCHIVED). * `eq` `String` **optional** * `in` `[String!]` **optional** * `updatedAt` `UpdatedAtFilter` **optional** * `gt` `String` **optional** * `lt` `String` **optional** ## Possible returns * `QuerySkuPricesConnection` `QuerySkuPricesConnection` - `edges` `[QuerySkuPricesConnectionEdge]` **nullable** - `pageInfo` `PageInfo!` **non-null** - `totalCount` `Int!` **non-null** # skus (https://developer.godaddy.com/en/docs/references/rest/catalog/sku/queries/skus) --- title: skus description: Query `skus` on the catalog subgraph (SKU). full: true --- query Requires `commerce.product:read`. Query `skus` on the catalog subgraph (SKU). ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `after` `String` **optional** * `attributeValues` `SKUAttributeValueFilter` **optional** * `has` `[String!]` **optional** * `before` `String` **optional** * `code` `SKUCodeFilter` **optional** * `contains` `String` **optional** — Filters SKUs where the code contains the specified string, case-insensitive. * `eq` `String` **optional** * `in` `[String!]` **optional** — Filters SKUs where the code matches any of the specified codes. * `createdAt` `CreatedAtFilter` **optional** * `gt` `String` **optional** * `lt` `String` **optional** * `eanCode` `SKUEanCodeFilter` **optional** * `eq` `String` **optional** * `in` `[String!]` **optional** * `first` `Int` **optional** * `gtinCode` `SKUGtinCodeFilter` **optional** * `eq` `String` **optional** * `in` `[String!]` **optional** * `id` `SKUIdsFilter` **optional** * `in` `[String!]` **optional** * `isbnCode` `SKUIsbnCodeFilter` **optional** * `eq` `String` **optional** * `in` `[String!]` **optional** * `label` `LabelFilter` **optional** * `contains` `String` **optional** — Filters items where the label contains the specified string, case-insensitive. * `eq` `String` **optional** * `last` `Int` **optional** * `locationId` `LocationIdFilter` **optional** * `eq` `String` **optional** * `name` `NameFilter` **optional** * `contains` `String` **optional** — Filters items where the name contains the specified string, case-insensitive. * `eq` `String` **optional** * `in` `[String!]` **optional** — Filters items where the name matches any of the specified names. * `orderBy` `SKUOrderBy` **optional** * `createdAt` `OrderByDirectionEnum` **optional** * `id` `OrderByDirectionEnum` **optional** * `label` `OrderByDirectionEnum` **optional** * `name` `OrderByDirectionEnum` **optional** * `price` `OrderByDirectionEnum` **optional** * `updatedAt` `OrderByDirectionEnum` **optional** * `paginationType` `PaginationType` **optional** Default: `"CURSOR"`. * `queryFilter` `String` **optional** — A string filter in the ODATA format. ex: "label eq 'shirt' and contains(code, '123')". Supported columns: `label`, `code` Supported operators: `eq`, `ne`, `lt`, `gt`, `and`, `or` Supported functions: `contains` * `referenceValue` `ReferenceValueFilter` **optional** * `eq` `String` **optional** * `in` `[String!]` **optional** * `skuGroupId` `SKUGroupIdFilter` **optional** * `eq` `String` **optional** * `in` `[String!]` **optional** * `skuGroupStatus` `SKUGroupStatusFilter` **optional** — Filter SKUs by their SKU group's status. SKUs without a SKU group will be excluded when this filter is present. * `eq` `String` **optional** * `in` `[String!]` **optional** * `status` `SKUStatusFilter` **optional** * `eq` `String` **optional** * `in` `[String!]` **optional** * `upcCode` `SKUUpcCodeFilter` **optional** * `eq` `String` **optional** * `in` `[String!]` **optional** * `updatedAt` `UpdatedAtFilter` **optional** * `gt` `String` **optional** * `lt` `String` **optional** ## Possible returns * `QuerySkusConnection` `QuerySkusConnection` - `edges` `[QuerySkusConnectionEdge]` **nullable** - `pageInfo` `PageInfo!` **non-null** - `totalCount` `Int!` **non-null** # addChannelsToSkuGroup (https://developer.godaddy.com/en/docs/references/rest/catalog/sku-group/mutations/addChannelsToSkuGroup) --- title: addChannelsToSkuGroup description: Add channels to an existing SKU group. full: true --- mutation Requires `commerce.product:write`. Add channels to an existing SKU group. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationAddChannelsToSkuGroupInput!` **required** * `channels` `[SKUGroupChannelAddInput!]!` **required** — The channels to add to the SKU group. These are pointers to the Channels API, Catalog API does not create the channel resources. * `channelId` `String!` **required** ## Possible returns * `SKUGroup` `SKUGroup` - `activatedAt` `DateTime` **nullable** — The timestamp of when the SKU was activated. - `archivedAt` `DateTime` **nullable** — The timestamp of when the SKU was archived. - `attributes` `SKUGroupAttributesConnection` **nullable** — Attributes of SKU Group. - `channelAssociationMode` `String` **nullable** — The channel association mode for this SKU Group. Can be ALL (uses active channels registered to the store) or SELECTIVE (uses custom channel associations). - `channels` `SKUGroupChannelsConnection` **nullable** — An association to a channel that exists in the Channel API. - `compareAtPriceRange` `PriceRange` **nullable** — The compare-at price range of the SKU group, showing min and max compare-at prices of SKUs in the group. - `createdAt` `DateTime!` **non-null** — The timestamp of when the SKU was created. - `description` `String` **nullable** — The merchant defined description of the group. - `htmlDescription` `String` **nullable** — HTML description for the SKU group. Will be used to display rich text content to customers. - `id` `ID!` **non-null** — The globally-unique ID of the group. - `label` `String` **nullable** — The display label of the group. - `lists` `SKUGroupListsConnection` **nullable** — A list is a group of SKU groups that are generally organized by similar characteristics. - `mediaObjects` `SKUGroupMediaObjectsConnection` **nullable** — Media objects stored under the SKU Group. - `metafields` `SKUGroupMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique human-friendly identifier for the group. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `options` `SKUGroupOptionsConnection` **nullable** — An option is a add-on that can be added on to a SKU group. - `priceRange` `PriceRange` **nullable** — The price range of the SKU group, showing min and max prices of SKUs in the group. - `references` `SKUGroupReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skuCount` `Int` **nullable** — The count of all SKUs associated with the SKU Group. Can be filtered by status. The default statuses are ACTIVE and DRAFT. - `skus` `SKUGroupSkusConnection` **nullable** — A SKU represents a stock keeping unit (SKU) in the catalog. - `status` `String!` **non-null** — The status of the SKU Group, one of `DRAFT`, `ACTIVE`, `ARCHIVED`. - `type` `String!` **non-null** — The type of the SKU Group, typically PHYSICAL or DIGITAL, but can also be a custom type. - `updatedAt` `DateTime!` **non-null** — The timestamp of when the SKU was updated. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the SKU group. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. - `shortLabel` `String` **nullable** deprecated — A short label for the group. Can be used instead of the label on smaller screens. Deprecated: Use channel-specific overrides for short labels. - `SKUs` `SKUGroupSKUsConnection` **nullable** deprecated — A SKU represents a stock keeping unit (SKU) in the catalog. Deprecated: Use skus instead. # addOptionsToSkuGroup (https://developer.godaddy.com/en/docs/references/rest/catalog/sku-group/mutations/addOptionsToSkuGroup) --- title: addOptionsToSkuGroup description: Add options to an existing SKU group. full: true --- mutation Requires `commerce.product:write`. Add options to an existing SKU group. For `SimpleMoneyInput.value`, send `1999` for $19.99 USD, not `19.99`. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationAddOptionsToSkuGroupInput!` **required** * `optionIds` `[String!]` **optional** — UUIDs of existing options to associate with this SKU group. * `options` `[CreateOptionInput!]` **optional** * `label` `String!` **required** * `type` `String!` **required** — The type of the Option, one of `TEXT`, `NUMBER`, `LIST`. Option Values are only available on the 'LIST' type. * `description` `String` **optional** * `metafields` `[CreateMetafieldInput!]` **optional** * `key` `String!` **required** * `namespace` `String!` **required** * `type` `String!` **required** — Metafield value type. Live catalog validation accepts lowercase values such as `boolean`, `string`, `stringMultiLine`, `number`, `numberDecimal`, `date`, `dateTime`, `json`, `measurement`, `url`, `reference`, `money`, `list.string`, `list.number`, `list.numberDecimal`. Uppercase `STRING` is rejected. * `value` `String!` **required** * `name` `String` **optional** — Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). * `position` `Int` **optional** * `prices` `[CreateOptionPriceInput!]` **optional** * `value` `SimpleMoneyInput!` **required** * `compareAtValue` `SimpleMoneyInput` **optional** * `validation` `CreateOptionValidationInput` **optional** * `max` `Int` **optional** * `min` `Int` **optional** * `values` `[CreateOptionValueInput!]` **optional** * `label` `String!` **required** * `metafields` `[CreateMetafieldInput!]` **optional** * `name` `String` **optional** — Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). * `position` `Int` **optional** * `prices` `[CreateOptionValuePriceInput!]` **optional** ## Possible returns * `SKUGroup` `SKUGroup` - `activatedAt` `DateTime` **nullable** — The timestamp of when the SKU was activated. - `archivedAt` `DateTime` **nullable** — The timestamp of when the SKU was archived. - `attributes` `SKUGroupAttributesConnection` **nullable** — Attributes of SKU Group. - `channelAssociationMode` `String` **nullable** — The channel association mode for this SKU Group. Can be ALL (uses active channels registered to the store) or SELECTIVE (uses custom channel associations). - `channels` `SKUGroupChannelsConnection` **nullable** — An association to a channel that exists in the Channel API. - `compareAtPriceRange` `PriceRange` **nullable** — The compare-at price range of the SKU group, showing min and max compare-at prices of SKUs in the group. - `createdAt` `DateTime!` **non-null** — The timestamp of when the SKU was created. - `description` `String` **nullable** — The merchant defined description of the group. - `htmlDescription` `String` **nullable** — HTML description for the SKU group. Will be used to display rich text content to customers. - `id` `ID!` **non-null** — The globally-unique ID of the group. - `label` `String` **nullable** — The display label of the group. - `lists` `SKUGroupListsConnection` **nullable** — A list is a group of SKU groups that are generally organized by similar characteristics. - `mediaObjects` `SKUGroupMediaObjectsConnection` **nullable** — Media objects stored under the SKU Group. - `metafields` `SKUGroupMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique human-friendly identifier for the group. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `options` `SKUGroupOptionsConnection` **nullable** — An option is a add-on that can be added on to a SKU group. - `priceRange` `PriceRange` **nullable** — The price range of the SKU group, showing min and max prices of SKUs in the group. - `references` `SKUGroupReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skuCount` `Int` **nullable** — The count of all SKUs associated with the SKU Group. Can be filtered by status. The default statuses are ACTIVE and DRAFT. - `skus` `SKUGroupSkusConnection` **nullable** — A SKU represents a stock keeping unit (SKU) in the catalog. - `status` `String!` **non-null** — The status of the SKU Group, one of `DRAFT`, `ACTIVE`, `ARCHIVED`. - `type` `String!` **non-null** — The type of the SKU Group, typically PHYSICAL or DIGITAL, but can also be a custom type. - `updatedAt` `DateTime!` **non-null** — The timestamp of when the SKU was updated. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the SKU group. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. - `shortLabel` `String` **nullable** deprecated — A short label for the group. Can be used instead of the label on smaller screens. Deprecated: Use channel-specific overrides for short labels. - `SKUs` `SKUGroupSKUsConnection` **nullable** deprecated — A SKU represents a stock keeping unit (SKU) in the catalog. Deprecated: Use skus instead. # addSkuGroupToLists (https://developer.godaddy.com/en/docs/references/rest/catalog/sku-group/mutations/addSkuGroupToLists) --- title: addSkuGroupToLists description: Add a single SKU Group to multiple lists full: true --- mutation Requires `commerce.product:write`. Add a single SKU Group to multiple lists ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationAddSkuGroupToListsInput!` **required** * `listIds` `[String!]!` **required** ## Possible returns * `SKUGroup` `SKUGroup` - `activatedAt` `DateTime` **nullable** — The timestamp of when the SKU was activated. - `archivedAt` `DateTime` **nullable** — The timestamp of when the SKU was archived. - `attributes` `SKUGroupAttributesConnection` **nullable** — Attributes of SKU Group. - `channelAssociationMode` `String` **nullable** — The channel association mode for this SKU Group. Can be ALL (uses active channels registered to the store) or SELECTIVE (uses custom channel associations). - `channels` `SKUGroupChannelsConnection` **nullable** — An association to a channel that exists in the Channel API. - `compareAtPriceRange` `PriceRange` **nullable** — The compare-at price range of the SKU group, showing min and max compare-at prices of SKUs in the group. - `createdAt` `DateTime!` **non-null** — The timestamp of when the SKU was created. - `description` `String` **nullable** — The merchant defined description of the group. - `htmlDescription` `String` **nullable** — HTML description for the SKU group. Will be used to display rich text content to customers. - `id` `ID!` **non-null** — The globally-unique ID of the group. - `label` `String` **nullable** — The display label of the group. - `lists` `SKUGroupListsConnection` **nullable** — A list is a group of SKU groups that are generally organized by similar characteristics. - `mediaObjects` `SKUGroupMediaObjectsConnection` **nullable** — Media objects stored under the SKU Group. - `metafields` `SKUGroupMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique human-friendly identifier for the group. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `options` `SKUGroupOptionsConnection` **nullable** — An option is a add-on that can be added on to a SKU group. - `priceRange` `PriceRange` **nullable** — The price range of the SKU group, showing min and max prices of SKUs in the group. - `references` `SKUGroupReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skuCount` `Int` **nullable** — The count of all SKUs associated with the SKU Group. Can be filtered by status. The default statuses are ACTIVE and DRAFT. - `skus` `SKUGroupSkusConnection` **nullable** — A SKU represents a stock keeping unit (SKU) in the catalog. - `status` `String!` **non-null** — The status of the SKU Group, one of `DRAFT`, `ACTIVE`, `ARCHIVED`. - `type` `String!` **non-null** — The type of the SKU Group, typically PHYSICAL or DIGITAL, but can also be a custom type. - `updatedAt` `DateTime!` **non-null** — The timestamp of when the SKU was updated. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the SKU group. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. - `shortLabel` `String` **nullable** deprecated — A short label for the group. Can be used instead of the label on smaller screens. Deprecated: Use channel-specific overrides for short labels. - `SKUs` `SKUGroupSKUsConnection` **nullable** deprecated — A SKU represents a stock keeping unit (SKU) in the catalog. Deprecated: Use skus instead. # addSkuGroupsToList (https://developer.godaddy.com/en/docs/references/rest/catalog/sku-group/mutations/addSkuGroupsToList) --- title: addSkuGroupsToList description: Add SKU Groups to an existing list. full: true --- mutation Requires `commerce.product:write`. Add SKU Groups to an existing list. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationAddSkuGroupsToListInput!` **required** * `skuGroupIds` `[String!]!` **required** ## Possible returns * `List` `List` — A list is a group of SKU groups that are generally organized by similar characteristics. - `createdAt` `DateTime!` **non-null** — The date and time of when the List was created. - `description` `String` **nullable** — A single-line textual description of the List. - `htmlDescription` `String` **nullable** — HTML description for the List. Will be used to display rich text content to customers. - `id` `ID!` **non-null** — The globally-unique ID of the List. - `label` `String` **nullable** — The display label of the List. - `mediaObjects` `ListMediaObjectsConnection` **nullable** — Media can be images, videos, or files - `metafields` `ListMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique name for the List. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `references` `ListReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skuGroups` `ListSkuGroupsConnection` **nullable** — A SKU Group is a grouping of related SKUs. It provides information about all of the SKUs that are sold together on storefronts or devices. - `status` `String` **nullable** — The status of the list, one of `ACTIVE`, `DRAFT`, `ARCHIVED`. - `updatedAt` `DateTime!` **non-null** — The date and time of when the List was updated. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the List. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. - `SKUGroups` `ListSKUGroupsConnection` **nullable** deprecated — A SKU Group is a grouping of related SKUs. It provides information about all of the SKUs that are sold together on storefronts or devices. Deprecated: Use skuGroups instead. # addSkusToSkuGroup (https://developer.godaddy.com/en/docs/references/rest/catalog/sku-group/mutations/addSkusToSkuGroup) --- title: addSkusToSkuGroup description: Add SKUs to an existing SKU group. full: true --- mutation Requires `commerce.product:write`. Add SKUs to an existing SKU group. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationAddSkusToSkuGroupInput!` **required** * `skuIds` `[String!]!` **required** ## Possible returns * `SKUGroup` `SKUGroup` - `activatedAt` `DateTime` **nullable** — The timestamp of when the SKU was activated. - `archivedAt` `DateTime` **nullable** — The timestamp of when the SKU was archived. - `attributes` `SKUGroupAttributesConnection` **nullable** — Attributes of SKU Group. - `channelAssociationMode` `String` **nullable** — The channel association mode for this SKU Group. Can be ALL (uses active channels registered to the store) or SELECTIVE (uses custom channel associations). - `channels` `SKUGroupChannelsConnection` **nullable** — An association to a channel that exists in the Channel API. - `compareAtPriceRange` `PriceRange` **nullable** — The compare-at price range of the SKU group, showing min and max compare-at prices of SKUs in the group. - `createdAt` `DateTime!` **non-null** — The timestamp of when the SKU was created. - `description` `String` **nullable** — The merchant defined description of the group. - `htmlDescription` `String` **nullable** — HTML description for the SKU group. Will be used to display rich text content to customers. - `id` `ID!` **non-null** — The globally-unique ID of the group. - `label` `String` **nullable** — The display label of the group. - `lists` `SKUGroupListsConnection` **nullable** — A list is a group of SKU groups that are generally organized by similar characteristics. - `mediaObjects` `SKUGroupMediaObjectsConnection` **nullable** — Media objects stored under the SKU Group. - `metafields` `SKUGroupMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique human-friendly identifier for the group. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `options` `SKUGroupOptionsConnection` **nullable** — An option is a add-on that can be added on to a SKU group. - `priceRange` `PriceRange` **nullable** — The price range of the SKU group, showing min and max prices of SKUs in the group. - `references` `SKUGroupReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skuCount` `Int` **nullable** — The count of all SKUs associated with the SKU Group. Can be filtered by status. The default statuses are ACTIVE and DRAFT. - `skus` `SKUGroupSkusConnection` **nullable** — A SKU represents a stock keeping unit (SKU) in the catalog. - `status` `String!` **non-null** — The status of the SKU Group, one of `DRAFT`, `ACTIVE`, `ARCHIVED`. - `type` `String!` **non-null** — The type of the SKU Group, typically PHYSICAL or DIGITAL, but can also be a custom type. - `updatedAt` `DateTime!` **non-null** — The timestamp of when the SKU was updated. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the SKU group. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. - `shortLabel` `String` **nullable** deprecated — A short label for the group. Can be used instead of the label on smaller screens. Deprecated: Use channel-specific overrides for short labels. - `SKUs` `SKUGroupSKUsConnection` **nullable** deprecated — A SKU represents a stock keeping unit (SKU) in the catalog. Deprecated: Use skus instead. # archiveSkuGroup (https://developer.godaddy.com/en/docs/references/rest/catalog/sku-group/mutations/archiveSkuGroup) --- title: archiveSkuGroup description: Archive an existing SKU Group. full: true --- mutation Requires `commerce.product:write`. Archive an existing SKU Group. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `cascadeArchive` `CascadeArchiveInput` **optional** * `skus` `Boolean` **optional** — Whether to cascade archive SKUs when archiving the SKU Group. * `id` `String!` **required** ## Possible returns * `SKUGroup` `SKUGroup` - `activatedAt` `DateTime` **nullable** — The timestamp of when the SKU was activated. - `archivedAt` `DateTime` **nullable** — The timestamp of when the SKU was archived. - `attributes` `SKUGroupAttributesConnection` **nullable** — Attributes of SKU Group. - `channelAssociationMode` `String` **nullable** — The channel association mode for this SKU Group. Can be ALL (uses active channels registered to the store) or SELECTIVE (uses custom channel associations). - `channels` `SKUGroupChannelsConnection` **nullable** — An association to a channel that exists in the Channel API. - `compareAtPriceRange` `PriceRange` **nullable** — The compare-at price range of the SKU group, showing min and max compare-at prices of SKUs in the group. - `createdAt` `DateTime!` **non-null** — The timestamp of when the SKU was created. - `description` `String` **nullable** — The merchant defined description of the group. - `htmlDescription` `String` **nullable** — HTML description for the SKU group. Will be used to display rich text content to customers. - `id` `ID!` **non-null** — The globally-unique ID of the group. - `label` `String` **nullable** — The display label of the group. - `lists` `SKUGroupListsConnection` **nullable** — A list is a group of SKU groups that are generally organized by similar characteristics. - `mediaObjects` `SKUGroupMediaObjectsConnection` **nullable** — Media objects stored under the SKU Group. - `metafields` `SKUGroupMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique human-friendly identifier for the group. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `options` `SKUGroupOptionsConnection` **nullable** — An option is a add-on that can be added on to a SKU group. - `priceRange` `PriceRange` **nullable** — The price range of the SKU group, showing min and max prices of SKUs in the group. - `references` `SKUGroupReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skuCount` `Int` **nullable** — The count of all SKUs associated with the SKU Group. Can be filtered by status. The default statuses are ACTIVE and DRAFT. - `skus` `SKUGroupSkusConnection` **nullable** — A SKU represents a stock keeping unit (SKU) in the catalog. - `status` `String!` **non-null** — The status of the SKU Group, one of `DRAFT`, `ACTIVE`, `ARCHIVED`. - `type` `String!` **non-null** — The type of the SKU Group, typically PHYSICAL or DIGITAL, but can also be a custom type. - `updatedAt` `DateTime!` **non-null** — The timestamp of when the SKU was updated. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the SKU group. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. - `shortLabel` `String` **nullable** deprecated — A short label for the group. Can be used instead of the label on smaller screens. Deprecated: Use channel-specific overrides for short labels. - `SKUs` `SKUGroupSKUsConnection` **nullable** deprecated — A SKU represents a stock keeping unit (SKU) in the catalog. Deprecated: Use skus instead. # createSkuGroup (https://developer.godaddy.com/en/docs/references/rest/catalog/sku-group/mutations/createSkuGroup) --- title: createSkuGroup description: Create a new SKU Group. full: true --- mutation Requires `commerce.product:write`. Create a new SKU Group. For `SimpleMoneyInput.value`, send `1999` for $19.99 USD, not `19.99`. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `input` `MutationCreateSkuGroupInput!` **required** * `label` `String!` **required** * `type` `String!` **required** * `attributes` `[CreateSKUGroupAttributeInput!]` **optional** * `label` `String!` **required** * `description` `String` **optional** * `metafields` `[CreateMetafieldInput!]` **optional** * `key` `String!` **required** * `namespace` `String!` **required** * `type` `String!` **required** — Metafield value type. Live catalog validation accepts lowercase values such as `boolean`, `string`, `stringMultiLine`, `number`, `numberDecimal`, `date`, `dateTime`, `json`, `measurement`, `url`, `reference`, `money`, `list.string`, `list.number`, `list.numberDecimal`. Uppercase `STRING` is rejected. * `value` `String!` **required** * `name` `String` **optional** — Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). * `position` `Int` **optional** * `values` `[AssociateAttributeValueInput!]` **optional** * `label` `String!` **required** * `name` `String` **optional** — Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). * `position` `Int` **optional** * `channels` `[SKUGroupChannelAddInput!]` **optional** * `channelId` `String!` **required** * `description` `String` **optional** * `htmlDescription` `String` **optional** * `HTMLDescription` `String` **optional** — Deprecated: Use htmlDescription instead. * `mediaObjects` `[CreateMediaObjectInput!]` **optional** * `type` `String!` **required** — The type of the media, one of `IMAGE`, `VIDEO`, `AUDIO`. * `url` `String!` **required** * `label` `String` **optional** * `metafields` `[CreateMetafieldInput!]` **optional** * `key` `String!` **required** * `namespace` `String!` **required** * `type` `String!` **required** — Metafield value type. Live catalog validation accepts lowercase values such as `boolean`, `string`, `stringMultiLine`, `number`, `numberDecimal`, `date`, `dateTime`, `json`, `measurement`, `url`, `reference`, `money`, `list.string`, `list.number`, `list.numberDecimal`. Uppercase `STRING` is rejected. * `value` `String!` **required** * `name` `String` **optional** — Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). * `position` `Int` **optional** * `metafields` `[CreateMetafieldInput!]` **optional** * `key` `String!` **required** * `namespace` `String!` **required** * `type` `String!` **required** — Metafield value type. Live catalog validation accepts lowercase values such as `boolean`, `string`, `stringMultiLine`, `number`, `numberDecimal`, `date`, `dateTime`, `json`, `measurement`, `url`, `reference`, `money`, `list.string`, `list.number`, `list.numberDecimal`. Uppercase `STRING` is rejected. * `value` `String!` **required** * `name` `String` **optional** — Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). * `options` `[CreateOptionInput!]` **optional** * `label` `String!` **required** * `type` `String!` **required** — The type of the Option, one of `TEXT`, `NUMBER`, `LIST`. Option Values are only available on the 'LIST' type. * `description` `String` **optional** * `metafields` `[CreateMetafieldInput!]` **optional** * `key` `String!` **required** * `namespace` `String!` **required** * `type` `String!` **required** — Metafield value type. Live catalog validation accepts lowercase values such as `boolean`, `string`, `stringMultiLine`, `number`, `numberDecimal`, `date`, `dateTime`, `json`, `measurement`, `url`, `reference`, `money`, `list.string`, `list.number`, `list.numberDecimal`. Uppercase `STRING` is rejected. * `value` `String!` **required** * `name` `String` **optional** — Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). * `position` `Int` **optional** * `prices` `[CreateOptionPriceInput!]` **optional** * `value` `SimpleMoneyInput!` **required** * `compareAtValue` `SimpleMoneyInput` **optional** * `validation` `CreateOptionValidationInput` **optional** * `max` `Int` **optional** * `min` `Int` **optional** * `values` `[CreateOptionValueInput!]` **optional** * `label` `String!` **required** * `metafields` `[CreateMetafieldInput!]` **optional** * `name` `String` **optional** — Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). * `position` `Int` **optional** * `prices` `[CreateOptionValuePriceInput!]` **optional** * `references` `[CreateReferenceInput!]` **optional** * `origin` `String!` **required** * `value` `String!` **required** * `shortLabel` `String` **optional** — Deprecated: Use channel-specific overrides for short labels. * `skus` `[CreateSKUGroupSKUInput!]` **optional** * `label` `String!` **required** * `backorderLimit` `Int` **optional** * `code` `String` **optional** * `cost` `Int` **optional** — DEPRECATED. Use unitCost instead. Deprecated: This cost field cannot specify currency code. Use `unitCost` instead. * `description` `String` **optional** * `disableInventoryTracking` `Boolean` **optional** * `disablePriceOverrides` `Boolean` **optional** * `disableShipping` `Boolean` **optional** * `eanCode` `String` **optional** * `gtinCode` `String` **optional** * `htmlDescription` `String` **optional** * `inventoryQuantities` `[CreateSKUInventoryInput!]` **optional** * `locationId` `String!` **required** * `quantity` `Int!` **required** * `isbnCode` `String` **optional** * `mediaObjects` `[CreateMediaObjectInput!]` **optional** * `type` `String!` **required** — The type of the media, one of `IMAGE`, `VIDEO`, `AUDIO`. * `url` `String!` **required** * `label` `String` **optional** * `metafields` `[CreateMetafieldInput!]` **optional** * `name` `String` **optional** — Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). * `position` `Int` **optional** * `metafields` `[CreateMetafieldInput!]` **optional** * `key` `String!` **required** * `namespace` `String!` **required** * `type` `String!` **required** — Metafield value type. Live catalog validation accepts lowercase values such as `boolean`, `string`, `stringMultiLine`, `number`, `numberDecimal`, `date`, `dateTime`, `json`, `measurement`, `url`, `reference`, `money`, `list.string`, `list.number`, `list.numberDecimal`. Uppercase `STRING` is rejected. * `value` `String!` **required** * `name` `String` **optional** — Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). * `prices` `[CreateSKUPriceInput!]` **optional** * `value` `SimpleMoneyInput!` **required** * `compareAtValue` `SimpleMoneyInput` **optional** * `references` `[CreateReferenceInput!]` **optional** * `origin` `String!` **required** * `value` `String!` **required** * `shortLabel` `String` **optional** * `status` `String` **optional** — The status of the SKU, one of `DRAFT`, `ACTIVE`, `ARCHIVED`. * `unitCost` `SimpleMoneyInput` **optional** * `currencyCode` `String!` **required** * `value` `Float!` **required** — Integer minor units in the smallest currency unit (for USD, cents: `1999` = $19.99). Send `1999`, not `19.99`. * `unitOfWeight` `String` **optional** — The unit of the weight, one of `KG`, `GR`, `LB`, `OZ`. * `upcCode` `String` **optional** * `weight` `Float` **optional** * `status` `String` **optional** — The status of the SKU, one of `DRAFT`, `ACTIVE`, `ARCHIVED`. ## Possible returns * `SKUGroup` `SKUGroup` - `activatedAt` `DateTime` **nullable** — The timestamp of when the SKU was activated. - `archivedAt` `DateTime` **nullable** — The timestamp of when the SKU was archived. - `attributes` `SKUGroupAttributesConnection` **nullable** — Attributes of SKU Group. - `channelAssociationMode` `String` **nullable** — The channel association mode for this SKU Group. Can be ALL (uses active channels registered to the store) or SELECTIVE (uses custom channel associations). - `channels` `SKUGroupChannelsConnection` **nullable** — An association to a channel that exists in the Channel API. - `compareAtPriceRange` `PriceRange` **nullable** — The compare-at price range of the SKU group, showing min and max compare-at prices of SKUs in the group. - `createdAt` `DateTime!` **non-null** — The timestamp of when the SKU was created. - `description` `String` **nullable** — The merchant defined description of the group. - `htmlDescription` `String` **nullable** — HTML description for the SKU group. Will be used to display rich text content to customers. - `id` `ID!` **non-null** — The globally-unique ID of the group. - `label` `String` **nullable** — The display label of the group. - `lists` `SKUGroupListsConnection` **nullable** — A list is a group of SKU groups that are generally organized by similar characteristics. - `mediaObjects` `SKUGroupMediaObjectsConnection` **nullable** — Media objects stored under the SKU Group. - `metafields` `SKUGroupMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique human-friendly identifier for the group. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `options` `SKUGroupOptionsConnection` **nullable** — An option is a add-on that can be added on to a SKU group. - `priceRange` `PriceRange` **nullable** — The price range of the SKU group, showing min and max prices of SKUs in the group. - `references` `SKUGroupReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skuCount` `Int` **nullable** — The count of all SKUs associated with the SKU Group. Can be filtered by status. The default statuses are ACTIVE and DRAFT. - `skus` `SKUGroupSkusConnection` **nullable** — A SKU represents a stock keeping unit (SKU) in the catalog. - `status` `String!` **non-null** — The status of the SKU Group, one of `DRAFT`, `ACTIVE`, `ARCHIVED`. - `type` `String!` **non-null** — The type of the SKU Group, typically PHYSICAL or DIGITAL, but can also be a custom type. - `updatedAt` `DateTime!` **non-null** — The timestamp of when the SKU was updated. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the SKU group. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. - `shortLabel` `String` **nullable** deprecated — A short label for the group. Can be used instead of the label on smaller screens. Deprecated: Use channel-specific overrides for short labels. - `SKUs` `SKUGroupSKUsConnection` **nullable** deprecated — A SKU represents a stock keeping unit (SKU) in the catalog. Deprecated: Use skus instead. # deleteSkuGroupById (https://developer.godaddy.com/en/docs/references/rest/catalog/sku-group/mutations/deleteSkuGroupById) --- title: deleteSkuGroupById description: >- WARNING: This mutation hard deletes an existing SKU Group and all its associated records. full: true --- mutation Requires `commerce.product:write`. WARNING: This mutation hard deletes an existing SKU Group and all its associated records. Successful deletes return `data.deleteSkuGroupById: null`. The example keeps a selection set. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** ## Possible returns * `SKUGroup` `SKUGroup` - `activatedAt` `DateTime` **nullable** — The timestamp of when the SKU was activated. - `archivedAt` `DateTime` **nullable** — The timestamp of when the SKU was archived. - `attributes` `SKUGroupAttributesConnection` **nullable** — Attributes of SKU Group. - `channelAssociationMode` `String` **nullable** — The channel association mode for this SKU Group. Can be ALL (uses active channels registered to the store) or SELECTIVE (uses custom channel associations). - `channels` `SKUGroupChannelsConnection` **nullable** — An association to a channel that exists in the Channel API. - `compareAtPriceRange` `PriceRange` **nullable** — The compare-at price range of the SKU group, showing min and max compare-at prices of SKUs in the group. - `createdAt` `DateTime!` **non-null** — The timestamp of when the SKU was created. - `description` `String` **nullable** — The merchant defined description of the group. - `htmlDescription` `String` **nullable** — HTML description for the SKU group. Will be used to display rich text content to customers. - `id` `ID!` **non-null** — The globally-unique ID of the group. - `label` `String` **nullable** — The display label of the group. - `lists` `SKUGroupListsConnection` **nullable** — A list is a group of SKU groups that are generally organized by similar characteristics. - `mediaObjects` `SKUGroupMediaObjectsConnection` **nullable** — Media objects stored under the SKU Group. - `metafields` `SKUGroupMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique human-friendly identifier for the group. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `options` `SKUGroupOptionsConnection` **nullable** — An option is a add-on that can be added on to a SKU group. - `priceRange` `PriceRange` **nullable** — The price range of the SKU group, showing min and max prices of SKUs in the group. - `references` `SKUGroupReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skuCount` `Int` **nullable** — The count of all SKUs associated with the SKU Group. Can be filtered by status. The default statuses are ACTIVE and DRAFT. - `skus` `SKUGroupSkusConnection` **nullable** — A SKU represents a stock keeping unit (SKU) in the catalog. - `status` `String!` **non-null** — The status of the SKU Group, one of `DRAFT`, `ACTIVE`, `ARCHIVED`. - `type` `String!` **non-null** — The type of the SKU Group, typically PHYSICAL or DIGITAL, but can also be a custom type. - `updatedAt` `DateTime!` **non-null** — The timestamp of when the SKU was updated. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the SKU group. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. - `shortLabel` `String` **nullable** deprecated — A short label for the group. Can be used instead of the label on smaller screens. Deprecated: Use channel-specific overrides for short labels. - `SKUs` `SKUGroupSKUsConnection` **nullable** deprecated — A SKU represents a stock keeping unit (SKU) in the catalog. Deprecated: Use skus instead. # removeChannelsFromSkuGroup (https://developer.godaddy.com/en/docs/references/rest/catalog/sku-group/mutations/removeChannelsFromSkuGroup) --- title: removeChannelsFromSkuGroup description: Remove channel associations from an existing SKU group. full: true --- mutation Requires `commerce.product:write`. Remove channel associations from an existing SKU group. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationRemoveChannelsFromSkuGroupInput!` **required** * `channelIds` `[String!]!` **required** ## Possible returns * `SKUGroup` `SKUGroup` - `activatedAt` `DateTime` **nullable** — The timestamp of when the SKU was activated. - `archivedAt` `DateTime` **nullable** — The timestamp of when the SKU was archived. - `attributes` `SKUGroupAttributesConnection` **nullable** — Attributes of SKU Group. - `channelAssociationMode` `String` **nullable** — The channel association mode for this SKU Group. Can be ALL (uses active channels registered to the store) or SELECTIVE (uses custom channel associations). - `channels` `SKUGroupChannelsConnection` **nullable** — An association to a channel that exists in the Channel API. - `compareAtPriceRange` `PriceRange` **nullable** — The compare-at price range of the SKU group, showing min and max compare-at prices of SKUs in the group. - `createdAt` `DateTime!` **non-null** — The timestamp of when the SKU was created. - `description` `String` **nullable** — The merchant defined description of the group. - `htmlDescription` `String` **nullable** — HTML description for the SKU group. Will be used to display rich text content to customers. - `id` `ID!` **non-null** — The globally-unique ID of the group. - `label` `String` **nullable** — The display label of the group. - `lists` `SKUGroupListsConnection` **nullable** — A list is a group of SKU groups that are generally organized by similar characteristics. - `mediaObjects` `SKUGroupMediaObjectsConnection` **nullable** — Media objects stored under the SKU Group. - `metafields` `SKUGroupMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique human-friendly identifier for the group. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `options` `SKUGroupOptionsConnection` **nullable** — An option is a add-on that can be added on to a SKU group. - `priceRange` `PriceRange` **nullable** — The price range of the SKU group, showing min and max prices of SKUs in the group. - `references` `SKUGroupReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skuCount` `Int` **nullable** — The count of all SKUs associated with the SKU Group. Can be filtered by status. The default statuses are ACTIVE and DRAFT. - `skus` `SKUGroupSkusConnection` **nullable** — A SKU represents a stock keeping unit (SKU) in the catalog. - `status` `String!` **non-null** — The status of the SKU Group, one of `DRAFT`, `ACTIVE`, `ARCHIVED`. - `type` `String!` **non-null** — The type of the SKU Group, typically PHYSICAL or DIGITAL, but can also be a custom type. - `updatedAt` `DateTime!` **non-null** — The timestamp of when the SKU was updated. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the SKU group. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. - `shortLabel` `String` **nullable** deprecated — A short label for the group. Can be used instead of the label on smaller screens. Deprecated: Use channel-specific overrides for short labels. - `SKUs` `SKUGroupSKUsConnection` **nullable** deprecated — A SKU represents a stock keeping unit (SKU) in the catalog. Deprecated: Use skus instead. # removeMetafieldsFromSkuGroup (https://developer.godaddy.com/en/docs/references/rest/catalog/sku-group/mutations/removeMetafieldsFromSkuGroup) --- title: removeMetafieldsFromSkuGroup description: Remove metafields from an existing SKU Group. full: true --- mutation Requires `commerce.product:write`. Remove metafields from an existing SKU Group. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationRemoveMetafieldsFromSkuGroupInput!` **required** * `metafields` `[RemoveMetafieldInput!]!` **required** * `key` `String!` **required** * `namespace` `String!` **required** ## Possible returns * `SKUGroup` `SKUGroup` - `activatedAt` `DateTime` **nullable** — The timestamp of when the SKU was activated. - `archivedAt` `DateTime` **nullable** — The timestamp of when the SKU was archived. - `attributes` `SKUGroupAttributesConnection` **nullable** — Attributes of SKU Group. - `channelAssociationMode` `String` **nullable** — The channel association mode for this SKU Group. Can be ALL (uses active channels registered to the store) or SELECTIVE (uses custom channel associations). - `channels` `SKUGroupChannelsConnection` **nullable** — An association to a channel that exists in the Channel API. - `compareAtPriceRange` `PriceRange` **nullable** — The compare-at price range of the SKU group, showing min and max compare-at prices of SKUs in the group. - `createdAt` `DateTime!` **non-null** — The timestamp of when the SKU was created. - `description` `String` **nullable** — The merchant defined description of the group. - `htmlDescription` `String` **nullable** — HTML description for the SKU group. Will be used to display rich text content to customers. - `id` `ID!` **non-null** — The globally-unique ID of the group. - `label` `String` **nullable** — The display label of the group. - `lists` `SKUGroupListsConnection` **nullable** — A list is a group of SKU groups that are generally organized by similar characteristics. - `mediaObjects` `SKUGroupMediaObjectsConnection` **nullable** — Media objects stored under the SKU Group. - `metafields` `SKUGroupMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique human-friendly identifier for the group. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `options` `SKUGroupOptionsConnection` **nullable** — An option is a add-on that can be added on to a SKU group. - `priceRange` `PriceRange` **nullable** — The price range of the SKU group, showing min and max prices of SKUs in the group. - `references` `SKUGroupReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skuCount` `Int` **nullable** — The count of all SKUs associated with the SKU Group. Can be filtered by status. The default statuses are ACTIVE and DRAFT. - `skus` `SKUGroupSkusConnection` **nullable** — A SKU represents a stock keeping unit (SKU) in the catalog. - `status` `String!` **non-null** — The status of the SKU Group, one of `DRAFT`, `ACTIVE`, `ARCHIVED`. - `type` `String!` **non-null** — The type of the SKU Group, typically PHYSICAL or DIGITAL, but can also be a custom type. - `updatedAt` `DateTime!` **non-null** — The timestamp of when the SKU was updated. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the SKU group. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. - `shortLabel` `String` **nullable** deprecated — A short label for the group. Can be used instead of the label on smaller screens. Deprecated: Use channel-specific overrides for short labels. - `SKUs` `SKUGroupSKUsConnection` **nullable** deprecated — A SKU represents a stock keeping unit (SKU) in the catalog. Deprecated: Use skus instead. # removeOptionsFromSkuGroup (https://developer.godaddy.com/en/docs/references/rest/catalog/sku-group/mutations/removeOptionsFromSkuGroup) --- title: removeOptionsFromSkuGroup description: Remove Options from an existing SKU group. full: true --- mutation Requires `commerce.product:write`. Remove Options from an existing SKU group. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationRemoveOptionsFromSkuGroupInput!` **required** * `optionIds` `[String!]!` **required** ## Possible returns * `SKUGroup` `SKUGroup` - `activatedAt` `DateTime` **nullable** — The timestamp of when the SKU was activated. - `archivedAt` `DateTime` **nullable** — The timestamp of when the SKU was archived. - `attributes` `SKUGroupAttributesConnection` **nullable** — Attributes of SKU Group. - `channelAssociationMode` `String` **nullable** — The channel association mode for this SKU Group. Can be ALL (uses active channels registered to the store) or SELECTIVE (uses custom channel associations). - `channels` `SKUGroupChannelsConnection` **nullable** — An association to a channel that exists in the Channel API. - `compareAtPriceRange` `PriceRange` **nullable** — The compare-at price range of the SKU group, showing min and max compare-at prices of SKUs in the group. - `createdAt` `DateTime!` **non-null** — The timestamp of when the SKU was created. - `description` `String` **nullable** — The merchant defined description of the group. - `htmlDescription` `String` **nullable** — HTML description for the SKU group. Will be used to display rich text content to customers. - `id` `ID!` **non-null** — The globally-unique ID of the group. - `label` `String` **nullable** — The display label of the group. - `lists` `SKUGroupListsConnection` **nullable** — A list is a group of SKU groups that are generally organized by similar characteristics. - `mediaObjects` `SKUGroupMediaObjectsConnection` **nullable** — Media objects stored under the SKU Group. - `metafields` `SKUGroupMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique human-friendly identifier for the group. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `options` `SKUGroupOptionsConnection` **nullable** — An option is a add-on that can be added on to a SKU group. - `priceRange` `PriceRange` **nullable** — The price range of the SKU group, showing min and max prices of SKUs in the group. - `references` `SKUGroupReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skuCount` `Int` **nullable** — The count of all SKUs associated with the SKU Group. Can be filtered by status. The default statuses are ACTIVE and DRAFT. - `skus` `SKUGroupSkusConnection` **nullable** — A SKU represents a stock keeping unit (SKU) in the catalog. - `status` `String!` **non-null** — The status of the SKU Group, one of `DRAFT`, `ACTIVE`, `ARCHIVED`. - `type` `String!` **non-null** — The type of the SKU Group, typically PHYSICAL or DIGITAL, but can also be a custom type. - `updatedAt` `DateTime!` **non-null** — The timestamp of when the SKU was updated. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the SKU group. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. - `shortLabel` `String` **nullable** deprecated — A short label for the group. Can be used instead of the label on smaller screens. Deprecated: Use channel-specific overrides for short labels. - `SKUs` `SKUGroupSKUsConnection` **nullable** deprecated — A SKU represents a stock keeping unit (SKU) in the catalog. Deprecated: Use skus instead. # removeSkuGroupFromLists (https://developer.godaddy.com/en/docs/references/rest/catalog/sku-group/mutations/removeSkuGroupFromLists) --- title: removeSkuGroupFromLists description: Remove a single SKU Group from multiple lists full: true --- mutation Requires `commerce.product:write`. Remove a single SKU Group from multiple lists ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationRemoveSkuGroupFromListsInput!` **required** * `listIds` `[String!]!` **required** ## Possible returns * `SKUGroup` `SKUGroup` - `activatedAt` `DateTime` **nullable** — The timestamp of when the SKU was activated. - `archivedAt` `DateTime` **nullable** — The timestamp of when the SKU was archived. - `attributes` `SKUGroupAttributesConnection` **nullable** — Attributes of SKU Group. - `channelAssociationMode` `String` **nullable** — The channel association mode for this SKU Group. Can be ALL (uses active channels registered to the store) or SELECTIVE (uses custom channel associations). - `channels` `SKUGroupChannelsConnection` **nullable** — An association to a channel that exists in the Channel API. - `compareAtPriceRange` `PriceRange` **nullable** — The compare-at price range of the SKU group, showing min and max compare-at prices of SKUs in the group. - `createdAt` `DateTime!` **non-null** — The timestamp of when the SKU was created. - `description` `String` **nullable** — The merchant defined description of the group. - `htmlDescription` `String` **nullable** — HTML description for the SKU group. Will be used to display rich text content to customers. - `id` `ID!` **non-null** — The globally-unique ID of the group. - `label` `String` **nullable** — The display label of the group. - `lists` `SKUGroupListsConnection` **nullable** — A list is a group of SKU groups that are generally organized by similar characteristics. - `mediaObjects` `SKUGroupMediaObjectsConnection` **nullable** — Media objects stored under the SKU Group. - `metafields` `SKUGroupMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique human-friendly identifier for the group. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `options` `SKUGroupOptionsConnection` **nullable** — An option is a add-on that can be added on to a SKU group. - `priceRange` `PriceRange` **nullable** — The price range of the SKU group, showing min and max prices of SKUs in the group. - `references` `SKUGroupReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skuCount` `Int` **nullable** — The count of all SKUs associated with the SKU Group. Can be filtered by status. The default statuses are ACTIVE and DRAFT. - `skus` `SKUGroupSkusConnection` **nullable** — A SKU represents a stock keeping unit (SKU) in the catalog. - `status` `String!` **non-null** — The status of the SKU Group, one of `DRAFT`, `ACTIVE`, `ARCHIVED`. - `type` `String!` **non-null** — The type of the SKU Group, typically PHYSICAL or DIGITAL, but can also be a custom type. - `updatedAt` `DateTime!` **non-null** — The timestamp of when the SKU was updated. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the SKU group. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. - `shortLabel` `String` **nullable** deprecated — A short label for the group. Can be used instead of the label on smaller screens. Deprecated: Use channel-specific overrides for short labels. - `SKUs` `SKUGroupSKUsConnection` **nullable** deprecated — A SKU represents a stock keeping unit (SKU) in the catalog. Deprecated: Use skus instead. # removeSkuGroupsFromList (https://developer.godaddy.com/en/docs/references/rest/catalog/sku-group/mutations/removeSkuGroupsFromList) --- title: removeSkuGroupsFromList description: Remove SKU Groups from an existing list. full: true --- mutation Requires `commerce.product:write`. Remove SKU Groups from an existing list. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationRemoveSkuGroupsFromListInput!` **required** * `skuGroupIds` `[String!]!` **required** ## Possible returns * `List` `List` — A list is a group of SKU groups that are generally organized by similar characteristics. - `createdAt` `DateTime!` **non-null** — The date and time of when the List was created. - `description` `String` **nullable** — A single-line textual description of the List. - `htmlDescription` `String` **nullable** — HTML description for the List. Will be used to display rich text content to customers. - `id` `ID!` **non-null** — The globally-unique ID of the List. - `label` `String` **nullable** — The display label of the List. - `mediaObjects` `ListMediaObjectsConnection` **nullable** — Media can be images, videos, or files - `metafields` `ListMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique name for the List. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `references` `ListReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skuGroups` `ListSkuGroupsConnection` **nullable** — A SKU Group is a grouping of related SKUs. It provides information about all of the SKUs that are sold together on storefronts or devices. - `status` `String` **nullable** — The status of the list, one of `ACTIVE`, `DRAFT`, `ARCHIVED`. - `updatedAt` `DateTime!` **non-null** — The date and time of when the List was updated. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the List. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. - `SKUGroups` `ListSKUGroupsConnection` **nullable** deprecated — A SKU Group is a grouping of related SKUs. It provides information about all of the SKUs that are sold together on storefronts or devices. Deprecated: Use skuGroups instead. # removeSkusFromSkuGroup (https://developer.godaddy.com/en/docs/references/rest/catalog/sku-group/mutations/removeSkusFromSkuGroup) --- title: removeSkusFromSkuGroup description: Remove SKUs from an existing SKU group. full: true --- mutation Requires `commerce.product:write`. Remove SKUs from an existing SKU group. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationRemoveSkusFromSkuGroupInput!` **required** * `skuIds` `[String!]!` **required** ## Possible returns * `SKUGroup` `SKUGroup` - `activatedAt` `DateTime` **nullable** — The timestamp of when the SKU was activated. - `archivedAt` `DateTime` **nullable** — The timestamp of when the SKU was archived. - `attributes` `SKUGroupAttributesConnection` **nullable** — Attributes of SKU Group. - `channelAssociationMode` `String` **nullable** — The channel association mode for this SKU Group. Can be ALL (uses active channels registered to the store) or SELECTIVE (uses custom channel associations). - `channels` `SKUGroupChannelsConnection` **nullable** — An association to a channel that exists in the Channel API. - `compareAtPriceRange` `PriceRange` **nullable** — The compare-at price range of the SKU group, showing min and max compare-at prices of SKUs in the group. - `createdAt` `DateTime!` **non-null** — The timestamp of when the SKU was created. - `description` `String` **nullable** — The merchant defined description of the group. - `htmlDescription` `String` **nullable** — HTML description for the SKU group. Will be used to display rich text content to customers. - `id` `ID!` **non-null** — The globally-unique ID of the group. - `label` `String` **nullable** — The display label of the group. - `lists` `SKUGroupListsConnection` **nullable** — A list is a group of SKU groups that are generally organized by similar characteristics. - `mediaObjects` `SKUGroupMediaObjectsConnection` **nullable** — Media objects stored under the SKU Group. - `metafields` `SKUGroupMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique human-friendly identifier for the group. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `options` `SKUGroupOptionsConnection` **nullable** — An option is a add-on that can be added on to a SKU group. - `priceRange` `PriceRange` **nullable** — The price range of the SKU group, showing min and max prices of SKUs in the group. - `references` `SKUGroupReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skuCount` `Int` **nullable** — The count of all SKUs associated with the SKU Group. Can be filtered by status. The default statuses are ACTIVE and DRAFT. - `skus` `SKUGroupSkusConnection` **nullable** — A SKU represents a stock keeping unit (SKU) in the catalog. - `status` `String!` **non-null** — The status of the SKU Group, one of `DRAFT`, `ACTIVE`, `ARCHIVED`. - `type` `String!` **non-null** — The type of the SKU Group, typically PHYSICAL or DIGITAL, but can also be a custom type. - `updatedAt` `DateTime!` **non-null** — The timestamp of when the SKU was updated. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the SKU group. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. - `shortLabel` `String` **nullable** deprecated — A short label for the group. Can be used instead of the label on smaller screens. Deprecated: Use channel-specific overrides for short labels. - `SKUs` `SKUGroupSKUsConnection` **nullable** deprecated — A SKU represents a stock keeping unit (SKU) in the catalog. Deprecated: Use skus instead. # setSkuGroupChannelAssociationMode (https://developer.godaddy.com/en/docs/references/rest/catalog/sku-group/mutations/setSkuGroupChannelAssociationMode) --- title: setSkuGroupChannelAssociationMode description: Set the channel association mode for a SKU Group. full: true --- mutation Requires `commerce.product:write`. Set the channel association mode for a SKU Group. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** — SKU Group ID * `input` `MutationSetSkuGroupChannelAssociationModeInput!` **required** * `mode` `String!` **required** — The channel association mode for this SKU Group. Can be ALL (uses active channels registered to the store) or SELECTIVE (uses custom channel associations). ## Possible returns * `SKUGroup` `SKUGroup` - `activatedAt` `DateTime` **nullable** — The timestamp of when the SKU was activated. - `archivedAt` `DateTime` **nullable** — The timestamp of when the SKU was archived. - `attributes` `SKUGroupAttributesConnection` **nullable** — Attributes of SKU Group. - `channelAssociationMode` `String` **nullable** — The channel association mode for this SKU Group. Can be ALL (uses active channels registered to the store) or SELECTIVE (uses custom channel associations). - `channels` `SKUGroupChannelsConnection` **nullable** — An association to a channel that exists in the Channel API. - `compareAtPriceRange` `PriceRange` **nullable** — The compare-at price range of the SKU group, showing min and max compare-at prices of SKUs in the group. - `createdAt` `DateTime!` **non-null** — The timestamp of when the SKU was created. - `description` `String` **nullable** — The merchant defined description of the group. - `htmlDescription` `String` **nullable** — HTML description for the SKU group. Will be used to display rich text content to customers. - `id` `ID!` **non-null** — The globally-unique ID of the group. - `label` `String` **nullable** — The display label of the group. - `lists` `SKUGroupListsConnection` **nullable** — A list is a group of SKU groups that are generally organized by similar characteristics. - `mediaObjects` `SKUGroupMediaObjectsConnection` **nullable** — Media objects stored under the SKU Group. - `metafields` `SKUGroupMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique human-friendly identifier for the group. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `options` `SKUGroupOptionsConnection` **nullable** — An option is a add-on that can be added on to a SKU group. - `priceRange` `PriceRange` **nullable** — The price range of the SKU group, showing min and max prices of SKUs in the group. - `references` `SKUGroupReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skuCount` `Int` **nullable** — The count of all SKUs associated with the SKU Group. Can be filtered by status. The default statuses are ACTIVE and DRAFT. - `skus` `SKUGroupSkusConnection` **nullable** — A SKU represents a stock keeping unit (SKU) in the catalog. - `status` `String!` **non-null** — The status of the SKU Group, one of `DRAFT`, `ACTIVE`, `ARCHIVED`. - `type` `String!` **non-null** — The type of the SKU Group, typically PHYSICAL or DIGITAL, but can also be a custom type. - `updatedAt` `DateTime!` **non-null** — The timestamp of when the SKU was updated. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the SKU group. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. - `shortLabel` `String` **nullable** deprecated — A short label for the group. Can be used instead of the label on smaller screens. Deprecated: Use channel-specific overrides for short labels. - `SKUs` `SKUGroupSKUsConnection` **nullable** deprecated — A SKU represents a stock keeping unit (SKU) in the catalog. Deprecated: Use skus instead. # updateSkuGroup (https://developer.godaddy.com/en/docs/references/rest/catalog/sku-group/mutations/updateSkuGroup) --- title: updateSkuGroup description: Update an existing SKU Group. full: true --- mutation Requires `commerce.product:write`. Update an existing SKU Group. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationUpdateSkuGroupInput!` **required** * `description` `String` **optional** * `htmlDescription` `String` **optional** * `label` `String` **optional** * `metafields` `[UpsertMetafieldInput!]` **optional** * `key` `String!` **required** * `namespace` `String!` **required** * `type` `String!` **required** * `value` `String!` **required** * `name` `String` **optional** — Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). * `shortLabel` `String` **optional** — Deprecated: Use channel-specific overrides for short labels. * `status` `String` **optional** — The status of the SKU, one of `DRAFT`, `ACTIVE`, `ARCHIVED`. ## Possible returns * `SKUGroup` `SKUGroup` - `activatedAt` `DateTime` **nullable** — The timestamp of when the SKU was activated. - `archivedAt` `DateTime` **nullable** — The timestamp of when the SKU was archived. - `attributes` `SKUGroupAttributesConnection` **nullable** — Attributes of SKU Group. - `channelAssociationMode` `String` **nullable** — The channel association mode for this SKU Group. Can be ALL (uses active channels registered to the store) or SELECTIVE (uses custom channel associations). - `channels` `SKUGroupChannelsConnection` **nullable** — An association to a channel that exists in the Channel API. - `compareAtPriceRange` `PriceRange` **nullable** — The compare-at price range of the SKU group, showing min and max compare-at prices of SKUs in the group. - `createdAt` `DateTime!` **non-null** — The timestamp of when the SKU was created. - `description` `String` **nullable** — The merchant defined description of the group. - `htmlDescription` `String` **nullable** — HTML description for the SKU group. Will be used to display rich text content to customers. - `id` `ID!` **non-null** — The globally-unique ID of the group. - `label` `String` **nullable** — The display label of the group. - `lists` `SKUGroupListsConnection` **nullable** — A list is a group of SKU groups that are generally organized by similar characteristics. - `mediaObjects` `SKUGroupMediaObjectsConnection` **nullable** — Media objects stored under the SKU Group. - `metafields` `SKUGroupMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique human-friendly identifier for the group. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `options` `SKUGroupOptionsConnection` **nullable** — An option is a add-on that can be added on to a SKU group. - `priceRange` `PriceRange` **nullable** — The price range of the SKU group, showing min and max prices of SKUs in the group. - `references` `SKUGroupReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skuCount` `Int` **nullable** — The count of all SKUs associated with the SKU Group. Can be filtered by status. The default statuses are ACTIVE and DRAFT. - `skus` `SKUGroupSkusConnection` **nullable** — A SKU represents a stock keeping unit (SKU) in the catalog. - `status` `String!` **non-null** — The status of the SKU Group, one of `DRAFT`, `ACTIVE`, `ARCHIVED`. - `type` `String!` **non-null** — The type of the SKU Group, typically PHYSICAL or DIGITAL, but can also be a custom type. - `updatedAt` `DateTime!` **non-null** — The timestamp of when the SKU was updated. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the SKU group. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. - `shortLabel` `String` **nullable** deprecated — A short label for the group. Can be used instead of the label on smaller screens. Deprecated: Use channel-specific overrides for short labels. - `SKUs` `SKUGroupSKUsConnection` **nullable** deprecated — A SKU represents a stock keeping unit (SKU) in the catalog. Deprecated: Use skus instead. # updateSkuGroupOptionPositions (https://developer.godaddy.com/en/docs/references/rest/catalog/sku-group/mutations/updateSkuGroupOptionPositions) --- title: updateSkuGroupOptionPositions description: >- Reorder options within a SKU group by updating the position of each option's association. full: true --- mutation Requires `commerce.product:write`. Reorder options within a SKU group by updating the position of each option's association. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** * `input` `MutationUpdateSkuGroupOptionPositionsInput!` **required** * `positions` `[UpdateSKUGroupOptionPositionInput!]!` **required** * `optionId` `String!` **required** * `position` `Int!` **required** ## Possible returns * `SKUGroup` `SKUGroup` - `activatedAt` `DateTime` **nullable** — The timestamp of when the SKU was activated. - `archivedAt` `DateTime` **nullable** — The timestamp of when the SKU was archived. - `attributes` `SKUGroupAttributesConnection` **nullable** — Attributes of SKU Group. - `channelAssociationMode` `String` **nullable** — The channel association mode for this SKU Group. Can be ALL (uses active channels registered to the store) or SELECTIVE (uses custom channel associations). - `channels` `SKUGroupChannelsConnection` **nullable** — An association to a channel that exists in the Channel API. - `compareAtPriceRange` `PriceRange` **nullable** — The compare-at price range of the SKU group, showing min and max compare-at prices of SKUs in the group. - `createdAt` `DateTime!` **non-null** — The timestamp of when the SKU was created. - `description` `String` **nullable** — The merchant defined description of the group. - `htmlDescription` `String` **nullable** — HTML description for the SKU group. Will be used to display rich text content to customers. - `id` `ID!` **non-null** — The globally-unique ID of the group. - `label` `String` **nullable** — The display label of the group. - `lists` `SKUGroupListsConnection` **nullable** — A list is a group of SKU groups that are generally organized by similar characteristics. - `mediaObjects` `SKUGroupMediaObjectsConnection` **nullable** — Media objects stored under the SKU Group. - `metafields` `SKUGroupMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique human-friendly identifier for the group. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `options` `SKUGroupOptionsConnection` **nullable** — An option is a add-on that can be added on to a SKU group. - `priceRange` `PriceRange` **nullable** — The price range of the SKU group, showing min and max prices of SKUs in the group. - `references` `SKUGroupReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skuCount` `Int` **nullable** — The count of all SKUs associated with the SKU Group. Can be filtered by status. The default statuses are ACTIVE and DRAFT. - `skus` `SKUGroupSkusConnection` **nullable** — A SKU represents a stock keeping unit (SKU) in the catalog. - `status` `String!` **non-null** — The status of the SKU Group, one of `DRAFT`, `ACTIVE`, `ARCHIVED`. - `type` `String!` **non-null** — The type of the SKU Group, typically PHYSICAL or DIGITAL, but can also be a custom type. - `updatedAt` `DateTime!` **non-null** — The timestamp of when the SKU was updated. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the SKU group. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. - `shortLabel` `String` **nullable** deprecated — A short label for the group. Can be used instead of the label on smaller screens. Deprecated: Use channel-specific overrides for short labels. - `SKUs` `SKUGroupSKUsConnection` **nullable** deprecated — A SKU represents a stock keeping unit (SKU) in the catalog. Deprecated: Use skus instead. # skuGroup (https://developer.godaddy.com/en/docs/references/rest/catalog/sku-group/queries/skuGroup) --- title: skuGroup description: Query `skuGroup` on the catalog subgraph (SKU group). full: true --- query Requires `commerce.product:read`. Query `skuGroup` on the catalog subgraph (SKU group). ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `String!` **required** ## Possible returns * `SKUGroup` `SKUGroup` - `activatedAt` `DateTime` **nullable** — The timestamp of when the SKU was activated. - `archivedAt` `DateTime` **nullable** — The timestamp of when the SKU was archived. - `attributes` `SKUGroupAttributesConnection` **nullable** — Attributes of SKU Group. - `channelAssociationMode` `String` **nullable** — The channel association mode for this SKU Group. Can be ALL (uses active channels registered to the store) or SELECTIVE (uses custom channel associations). - `channels` `SKUGroupChannelsConnection` **nullable** — An association to a channel that exists in the Channel API. - `compareAtPriceRange` `PriceRange` **nullable** — The compare-at price range of the SKU group, showing min and max compare-at prices of SKUs in the group. - `createdAt` `DateTime!` **non-null** — The timestamp of when the SKU was created. - `description` `String` **nullable** — The merchant defined description of the group. - `htmlDescription` `String` **nullable** — HTML description for the SKU group. Will be used to display rich text content to customers. - `id` `ID!` **non-null** — The globally-unique ID of the group. - `label` `String` **nullable** — The display label of the group. - `lists` `SKUGroupListsConnection` **nullable** — A list is a group of SKU groups that are generally organized by similar characteristics. - `mediaObjects` `SKUGroupMediaObjectsConnection` **nullable** — Media objects stored under the SKU Group. - `metafields` `SKUGroupMetafieldsConnection` **nullable** - `name` `String!` **non-null** — A unique human-friendly identifier for the group. Must be lowercase alphanumeric characters, and may include `-` or `_` (unique where noted). - `options` `SKUGroupOptionsConnection` **nullable** — An option is a add-on that can be added on to a SKU group. - `priceRange` `PriceRange` **nullable** — The price range of the SKU group, showing min and max prices of SKUs in the group. - `references` `SKUGroupReferencesConnection` **nullable** — A reference to the resource in an external service. This can be useful for integrating the resource to any external service. - `skuCount` `Int` **nullable** — The count of all SKUs associated with the SKU Group. Can be filtered by status. The default statuses are ACTIVE and DRAFT. - `skus` `SKUGroupSkusConnection` **nullable** — A SKU represents a stock keeping unit (SKU) in the catalog. - `status` `String!` **non-null** — The status of the SKU Group, one of `DRAFT`, `ACTIVE`, `ARCHIVED`. - `type` `String!` **non-null** — The type of the SKU Group, typically PHYSICAL or DIGITAL, but can also be a custom type. - `updatedAt` `DateTime!` **non-null** — The timestamp of when the SKU was updated. - `HTMLDescription` `String` **nullable** deprecated — HTML description for the SKU group. Will be used to display rich text content to customers. Deprecated: Use htmlDescription instead. - `shortLabel` `String` **nullable** deprecated — A short label for the group. Can be used instead of the label on smaller screens. Deprecated: Use channel-specific overrides for short labels. - `SKUs` `SKUGroupSKUsConnection` **nullable** deprecated — A SKU represents a stock keeping unit (SKU) in the catalog. Deprecated: Use skus instead. # skuGroups (https://developer.godaddy.com/en/docs/references/rest/catalog/sku-group/queries/skuGroups) --- title: skuGroups description: Query `skuGroups` on the catalog subgraph (SKU group). full: true --- query Requires `commerce.product:read`. Query `skuGroups` on the catalog subgraph (SKU group). ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `after` `String` **optional** * `before` `String` **optional** * `channelId` `SKUGroupChannelIdFilter` **optional** * `eq` `String` **optional** * `in` `[String!]` **optional** * `createdAt` `CreatedAtFilter` **optional** * `gt` `String` **optional** * `lt` `String` **optional** * `first` `Int` **optional** * `hasCompareAt` `HasCompareAtFilter` **optional** * `currencyCode` `String!` **required** — The three-letter currency code of prices to match. * `exists` `Boolean!` **required** — When true, returns items with at least one price that has a compareAtValue > 0 (on sale) in the requested currency. When false, returns items that have at least one price in the requested currency but none with a compareAtValue > 0 (available at regular price in that currency). * `hasSKUs` `Boolean` **optional** — When true, returns only SKU groups with at least one SKU. When false, returns only SKU groups with zero SKUs. * `id` `SKUGroupIdsFilter` **optional** * `eq` `String` **optional** * `in` `[String!]` **optional** * `label` `LabelFilter` **optional** * `contains` `String` **optional** — Filters items where the label contains the specified string, case-insensitive. * `eq` `String` **optional** * `last` `Int` **optional** * `listId` `ListIdFilter` **optional** * `eq` `String` **optional** * `in` `[String!]` **optional** * `isNull` `Boolean` **optional** * `name` `NameFilter` **optional** * `contains` `String` **optional** — Filters items where the name contains the specified string, case-insensitive. * `eq` `String` **optional** * `in` `[String!]` **optional** — Filters items where the name matches any of the specified names. * `orderBy` `SKUGroupOrderBy` **optional** * `createdAt` `OrderByDirectionEnum` **optional** * `id` `OrderByDirectionEnum` **optional** * `label` `OrderByDirectionEnum` **optional** * `lowestPrice` `OrderByDirectionEnum` **optional** * `name` `OrderByDirectionEnum` **optional** * `saleCount` `OrderByDirectionEnum` **optional** * `updatedAt` `OrderByDirectionEnum` **optional** * `paginationType` `PaginationType` **optional** Default: `"CURSOR"`. * `priceRange` `PriceRangeFilter` **optional** * `currencyCode` `String!` **required** — The three-letter currency code of prices to match. * `max` `Float` **optional** — The inclusive maximum integer price value. At least one of min or max is required. * `min` `Float` **optional** — The inclusive minimum integer price value. At least one of min or max is required. * `referenceValue` `ReferenceValueFilter` **optional** * `eq` `String` **optional** * `in` `[String!]` **optional** * `status` `SKUGroupStatusFilter` **optional** * `eq` `String` **optional** * `in` `[String!]` **optional** * `type` `SKUGroupTypeFilter` **optional** * `eq` `String` **optional** * `in` `[String!]` **optional** * `updatedAt` `UpdatedAtFilter` **optional** * `gt` `String` **optional** * `lt` `String` **optional** ## Possible returns * `QuerySkuGroupsConnection` `QuerySkuGroupsConnection` - `edges` `[QuerySkuGroupsConnectionEdge]` **nullable** - `pageInfo` `PageInfo!` **non-null** - `totalCount` `Int!` **non-null** # applyDiscount (https://developer.godaddy.com/en/docs/references/rest/orders/discount/mutations/applyDiscount) --- title: applyDiscount description: >- Alias for applyDiscountCodes - Apply a discount to an existing order Deprecated: Use applyDiscountCodes instead. This field will be removed in a future release. full: true --- mutation Requires one of `commerce.order:create`, `commerce.order:update`, `commerce.order:cancel`, or `commerce.order:complete` (use the scope that matches the operation). Alias for applyDiscountCodes - Apply a discount to an existing order Deprecated: Use applyDiscountCodes instead. This field will be removed in a future release. Deprecated: Use applyDiscountCodes instead. This field will be removed in a future release. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `input` `ApplyDiscountCodesInput!` **required** * `discountCodes` `[String!]!` **required** * `orderId` `ID!` **required** — Global ID in format `Order_\` ## Possible returns * `Order` `Order` - `billing` `BillingInfo` **nullable** — Order level billing snapshot information - `canceledAt` `DateTime` **nullable** — The datetime when the order was canceled - `cartId` `String` **nullable** — ID associated with a cart. Used to link orders and carts for Inventory tracking purposes - `completedAt` `DateTime` **nullable** — The datetime when the order was completed - `context` `Context` **nullable** — Context for an order - `createdAt` `DateTime` **nullable** — The datetime when the order was created in our system - `customerId` `String` **nullable** — Reference to a Customer as defined by the Connections service - `discounts` `[Discount!]` **nullable** — Discounts for an order - `externalId` `String` **nullable** — External identifier for the order. If provided, it must be a unique identifier at a channel level - `fees` `[Fee!]` **nullable** — Fees for an order - `fulfilledAt` `DateTime` **nullable** — The datetime when the order was completely fulfilled - `fulfillmentModes` `[String!]` **nullable** — Fulfillment modes for an order - `history` `[OrderHistoryType!]` **nullable** — History for an order - `id` `ID!` **non-null** — An identifier unique to the order node. Auto-generated by the service on the fly - `inventoryAction` `InventoryAction` **nullable** — Controls inventory adjustment behavior for this order - `lineItems` `[LineItem!]` **nullable** — Line items for an order - `links` `[Links!]` **nullable** — A request-related [HATEOAS link](https://datatracker.ietf.org/doc/html/draft-handrews-json-schema-hyperschema-02). - `metafields` `[OrderMetafield!]` **nullable** — Metafields that allow clients to specify more information about the order. Attributes present in this object will not map across all channels - `notes` `[Note!]` **nullable** — Notes for an order - `number` `String` **nullable** — An identifier unique to the order. The `number` field can be used to map an existing order to an order in the Order Service. Null until the order is assigned a number (for example, DRAFT orders). - `numberDisplay` `String` **nullable** — A human readable order number handed out to customers. Used for any communications with the customer (e.g. emails, SMS, or invoices). If not provided on creation, it will match the `number` attribute - `paidAt` `DateTime` **nullable** — The datetime when the order was completely paid - `processedAt` `DateTime` **nullable** — The datetime when the order was processed. If you are importing orders from an app or another platform, then you can set `processedAt` to a datetime in the past to match when the original order was created - `refundedAt` `DateTime` **nullable** — The datetime when the order was completely refunded - `returnTotals` `OrderReturnTotals` **nullable** — Grouped totals for an order return - `shipping` `ShippingInfo` **nullable** — Order level shipping snapshot information - `shippingLines` `[ShippingLine!]` **nullable** — Shipping lines for an order - `staffUserIds` `[String!]` **nullable** — Staff users associated with the Order - `statuses` `OrderStatuses` **nullable** — Current fulfillment status, payment status, and main status for the order - `tags` `[String!]` **nullable** — Comma delimited string of tags for an order. A tag should be an attribute of the order that does not change - `taxes` `[OrderTax!]` **nullable** — Taxes for an order - `taxExempted` `Boolean` **nullable** — Details whether the order is tax exempt - `totals` `OrderTotals` **nullable** — Grouped totals for an order - `transactionIds` `[String!]` **nullable** — Transactions as defined by the Transaction Service associated with the Order - `updatedAt` `DateTime` **nullable** — The datetime when the order was last updated in our system - `deprecatedNote` `String` **nullable** deprecated — Merchant note for an Order Deprecated: Replaced by the notes array # applyDiscountCodes (https://developer.godaddy.com/en/docs/references/rest/orders/discount/mutations/applyDiscountCodes) --- title: applyDiscountCodes description: Apply a discount to an existing order full: true --- mutation Requires one of `commerce.order:create`, `commerce.order:update`, `commerce.order:cancel`, or `commerce.order:complete` (use the scope that matches the operation). Apply a discount to an existing order ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `input` `ApplyDiscountCodesInput!` **required** * `discountCodes` `[String!]!` **required** * `orderId` `ID!` **required** — Global ID in format `Order_\` ## Possible returns * `Order` `Order` - `billing` `BillingInfo` **nullable** — Order level billing snapshot information - `canceledAt` `DateTime` **nullable** — The datetime when the order was canceled - `cartId` `String` **nullable** — ID associated with a cart. Used to link orders and carts for Inventory tracking purposes - `completedAt` `DateTime` **nullable** — The datetime when the order was completed - `context` `Context` **nullable** — Context for an order - `createdAt` `DateTime` **nullable** — The datetime when the order was created in our system - `customerId` `String` **nullable** — Reference to a Customer as defined by the Connections service - `discounts` `[Discount!]` **nullable** — Discounts for an order - `externalId` `String` **nullable** — External identifier for the order. If provided, it must be a unique identifier at a channel level - `fees` `[Fee!]` **nullable** — Fees for an order - `fulfilledAt` `DateTime` **nullable** — The datetime when the order was completely fulfilled - `fulfillmentModes` `[String!]` **nullable** — Fulfillment modes for an order - `history` `[OrderHistoryType!]` **nullable** — History for an order - `id` `ID!` **non-null** — An identifier unique to the order node. Auto-generated by the service on the fly - `inventoryAction` `InventoryAction` **nullable** — Controls inventory adjustment behavior for this order - `lineItems` `[LineItem!]` **nullable** — Line items for an order - `links` `[Links!]` **nullable** — A request-related [HATEOAS link](https://datatracker.ietf.org/doc/html/draft-handrews-json-schema-hyperschema-02). - `metafields` `[OrderMetafield!]` **nullable** — Metafields that allow clients to specify more information about the order. Attributes present in this object will not map across all channels - `notes` `[Note!]` **nullable** — Notes for an order - `number` `String` **nullable** — An identifier unique to the order. The `number` field can be used to map an existing order to an order in the Order Service. Null until the order is assigned a number (for example, DRAFT orders). - `numberDisplay` `String` **nullable** — A human readable order number handed out to customers. Used for any communications with the customer (e.g. emails, SMS, or invoices). If not provided on creation, it will match the `number` attribute - `paidAt` `DateTime` **nullable** — The datetime when the order was completely paid - `processedAt` `DateTime` **nullable** — The datetime when the order was processed. If you are importing orders from an app or another platform, then you can set `processedAt` to a datetime in the past to match when the original order was created - `refundedAt` `DateTime` **nullable** — The datetime when the order was completely refunded - `returnTotals` `OrderReturnTotals` **nullable** — Grouped totals for an order return - `shipping` `ShippingInfo` **nullable** — Order level shipping snapshot information - `shippingLines` `[ShippingLine!]` **nullable** — Shipping lines for an order - `staffUserIds` `[String!]` **nullable** — Staff users associated with the Order - `statuses` `OrderStatuses` **nullable** — Current fulfillment status, payment status, and main status for the order - `tags` `[String!]` **nullable** — Comma delimited string of tags for an order. A tag should be an attribute of the order that does not change - `taxes` `[OrderTax!]` **nullable** — Taxes for an order - `taxExempted` `Boolean` **nullable** — Details whether the order is tax exempt - `totals` `OrderTotals` **nullable** — Grouped totals for an order - `transactionIds` `[String!]` **nullable** — Transactions as defined by the Transaction Service associated with the Order - `updatedAt` `DateTime` **nullable** — The datetime when the order was last updated in our system - `deprecatedNote` `String` **nullable** deprecated — Merchant note for an Order Deprecated: Replaced by the notes array # addDraftOrder (https://developer.godaddy.com/en/docs/references/rest/orders/draft-order/mutations/addDraftOrder) --- title: addDraftOrder description: Create a new draft order full: true --- mutation Requires one of `commerce.order:create`, `commerce.order:update`, `commerce.order:cancel`, or `commerce.order:complete` (use the scope that matches the operation). Create a new draft order ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `input` `AddDraftOrderInput!` **required** * `context` `OrderContextInput!` **required** * `billing` `OrderBillingInfoInput` **optional** * `canceledAt` `DateTime` **optional** * `cartId` `String` **optional** * `completedAt` `DateTime` **optional** * `customerId` `String` **optional** * `discounts` `[DiscountInput!]` **optional** * `externalId` `String` **optional** * `fees` `[FeeInput!]` **optional** * `fulfilledAt` `DateTime` **optional** * `fulfillmentModes` `[String!]` **optional** — Automatically set based on lineItem fulfillment modes. This field is read-only. * `inventoryAction` `InventoryAction` **optional** * `lineItems` `[CreateDraftLineItemInput!]` **optional** * `metafields` `[OrderMetafieldInput!]` **optional** * `notes` `[NoteInput!]` **optional** * `number` `String` **optional** * `numberDisplay` `String` **optional** * `paidAt` `DateTime` **optional** * `refundedAt` `DateTime` **optional** * `shipping` `OrderShippingInfoInput` **optional** * `shippingLines` `[ShippingLineInput!]` **optional** * `staffUserIds` `[String!]` **optional** * `tags` `[String!]` **optional** * `taxes` `[OrderTaxInput!]` **optional** * `taxExempted` `Boolean` **optional** * `totals` `OrderTotalsInput` **optional** — Deprecated: Totals are now auto-calculated and should not be manually set * `transactionIds` `[String!]` **optional** ## Possible returns * `Order` `Order` - `billing` `BillingInfo` **nullable** — Order level billing snapshot information - `canceledAt` `DateTime` **nullable** — The datetime when the order was canceled - `cartId` `String` **nullable** — ID associated with a cart. Used to link orders and carts for Inventory tracking purposes - `completedAt` `DateTime` **nullable** — The datetime when the order was completed - `context` `Context` **nullable** — Context for an order - `createdAt` `DateTime` **nullable** — The datetime when the order was created in our system - `customerId` `String` **nullable** — Reference to a Customer as defined by the Connections service - `discounts` `[Discount!]` **nullable** — Discounts for an order - `externalId` `String` **nullable** — External identifier for the order. If provided, it must be a unique identifier at a channel level - `fees` `[Fee!]` **nullable** — Fees for an order - `fulfilledAt` `DateTime` **nullable** — The datetime when the order was completely fulfilled - `fulfillmentModes` `[String!]` **nullable** — Fulfillment modes for an order - `history` `[OrderHistoryType!]` **nullable** — History for an order - `id` `ID!` **non-null** — An identifier unique to the order node. Auto-generated by the service on the fly - `inventoryAction` `InventoryAction` **nullable** — Controls inventory adjustment behavior for this order - `lineItems` `[LineItem!]` **nullable** — Line items for an order - `links` `[Links!]` **nullable** — A request-related [HATEOAS link](https://datatracker.ietf.org/doc/html/draft-handrews-json-schema-hyperschema-02). - `metafields` `[OrderMetafield!]` **nullable** — Metafields that allow clients to specify more information about the order. Attributes present in this object will not map across all channels - `notes` `[Note!]` **nullable** — Notes for an order - `number` `String` **nullable** — An identifier unique to the order. The `number` field can be used to map an existing order to an order in the Order Service. Null until the order is assigned a number (for example, DRAFT orders). - `numberDisplay` `String` **nullable** — A human readable order number handed out to customers. Used for any communications with the customer (e.g. emails, SMS, or invoices). If not provided on creation, it will match the `number` attribute - `paidAt` `DateTime` **nullable** — The datetime when the order was completely paid - `processedAt` `DateTime` **nullable** — The datetime when the order was processed. If you are importing orders from an app or another platform, then you can set `processedAt` to a datetime in the past to match when the original order was created - `refundedAt` `DateTime` **nullable** — The datetime when the order was completely refunded - `returnTotals` `OrderReturnTotals` **nullable** — Grouped totals for an order return - `shipping` `ShippingInfo` **nullable** — Order level shipping snapshot information - `shippingLines` `[ShippingLine!]` **nullable** — Shipping lines for an order - `staffUserIds` `[String!]` **nullable** — Staff users associated with the Order - `statuses` `OrderStatuses` **nullable** — Current fulfillment status, payment status, and main status for the order - `tags` `[String!]` **nullable** — Comma delimited string of tags for an order. A tag should be an attribute of the order that does not change - `taxes` `[OrderTax!]` **nullable** — Taxes for an order - `taxExempted` `Boolean` **nullable** — Details whether the order is tax exempt - `totals` `OrderTotals` **nullable** — Grouped totals for an order - `transactionIds` `[String!]` **nullable** — Transactions as defined by the Transaction Service associated with the Order - `updatedAt` `DateTime` **nullable** — The datetime when the order was last updated in our system - `deprecatedNote` `String` **nullable** deprecated — Merchant note for an Order Deprecated: Replaced by the notes array # updateDraftOrder (https://developer.godaddy.com/en/docs/references/rest/orders/draft-order/mutations/updateDraftOrder) --- title: updateDraftOrder description: Update an existing draft order full: true --- mutation Requires one of `commerce.order:create`, `commerce.order:update`, `commerce.order:cancel`, or `commerce.order:complete` (use the scope that matches the operation). Update an existing draft order ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `input` `UpdateDraftOrderInput!` **required** * `context` `OrderContextInputUpdate!` **required** * `id` `ID!` **required** * `billing` `OrderBillingInfoInput` **optional** * `cartId` `String` **optional** * `customerId` `String` **optional** * `discounts` `[UpdateDiscountInput!]` **optional** * `externalId` `String` **optional** * `fees` `[UpdateFeeInput!]` **optional** * `fulfillmentModes` `[String!]` **optional** — Automatically set based on lineItem fulfillment modes. This field is read-only. * `lineItems` `UpdateDraftOrderLineItemsInput` **optional** * `metafields` `[OrderMetafieldInput!]` **optional** * `notes` `[UpdateNoteInput!]` **optional** * `number` `String` **optional** * `shipping` `OrderShippingInfoInput` **optional** * `shippingLines` `[UpdateShippingLineInput!]` **optional** * `staffUserIds` `[String!]` **optional** * `tags` `[String!]` **optional** * `taxes` `[UpdateOrderTaxInput!]` **optional** * `totals` `OrderTotalsInput` **optional** — Deprecated: Totals are now auto-calculated and should not be manually set ## Possible returns * `Order` `Order` - `billing` `BillingInfo` **nullable** — Order level billing snapshot information - `canceledAt` `DateTime` **nullable** — The datetime when the order was canceled - `cartId` `String` **nullable** — ID associated with a cart. Used to link orders and carts for Inventory tracking purposes - `completedAt` `DateTime` **nullable** — The datetime when the order was completed - `context` `Context` **nullable** — Context for an order - `createdAt` `DateTime` **nullable** — The datetime when the order was created in our system - `customerId` `String` **nullable** — Reference to a Customer as defined by the Connections service - `discounts` `[Discount!]` **nullable** — Discounts for an order - `externalId` `String` **nullable** — External identifier for the order. If provided, it must be a unique identifier at a channel level - `fees` `[Fee!]` **nullable** — Fees for an order - `fulfilledAt` `DateTime` **nullable** — The datetime when the order was completely fulfilled - `fulfillmentModes` `[String!]` **nullable** — Fulfillment modes for an order - `history` `[OrderHistoryType!]` **nullable** — History for an order - `id` `ID!` **non-null** — An identifier unique to the order node. Auto-generated by the service on the fly - `inventoryAction` `InventoryAction` **nullable** — Controls inventory adjustment behavior for this order - `lineItems` `[LineItem!]` **nullable** — Line items for an order - `links` `[Links!]` **nullable** — A request-related [HATEOAS link](https://datatracker.ietf.org/doc/html/draft-handrews-json-schema-hyperschema-02). - `metafields` `[OrderMetafield!]` **nullable** — Metafields that allow clients to specify more information about the order. Attributes present in this object will not map across all channels - `notes` `[Note!]` **nullable** — Notes for an order - `number` `String` **nullable** — An identifier unique to the order. The `number` field can be used to map an existing order to an order in the Order Service. Null until the order is assigned a number (for example, DRAFT orders). - `numberDisplay` `String` **nullable** — A human readable order number handed out to customers. Used for any communications with the customer (e.g. emails, SMS, or invoices). If not provided on creation, it will match the `number` attribute - `paidAt` `DateTime` **nullable** — The datetime when the order was completely paid - `processedAt` `DateTime` **nullable** — The datetime when the order was processed. If you are importing orders from an app or another platform, then you can set `processedAt` to a datetime in the past to match when the original order was created - `refundedAt` `DateTime` **nullable** — The datetime when the order was completely refunded - `returnTotals` `OrderReturnTotals` **nullable** — Grouped totals for an order return - `shipping` `ShippingInfo` **nullable** — Order level shipping snapshot information - `shippingLines` `[ShippingLine!]` **nullable** — Shipping lines for an order - `staffUserIds` `[String!]` **nullable** — Staff users associated with the Order - `statuses` `OrderStatuses` **nullable** — Current fulfillment status, payment status, and main status for the order - `tags` `[String!]` **nullable** — Comma delimited string of tags for an order. A tag should be an attribute of the order that does not change - `taxes` `[OrderTax!]` **nullable** — Taxes for an order - `taxExempted` `Boolean` **nullable** — Details whether the order is tax exempt - `totals` `OrderTotals` **nullable** — Grouped totals for an order - `transactionIds` `[String!]` **nullable** — Transactions as defined by the Transaction Service associated with the Order - `updatedAt` `DateTime` **nullable** — The datetime when the order was last updated in our system - `deprecatedNote` `String` **nullable** deprecated — Merchant note for an Order Deprecated: Replaced by the notes array # updateDraftOrderBillingInfo (https://developer.godaddy.com/en/docs/references/rest/orders/draft-order/mutations/updateDraftOrderBillingInfo) --- title: updateDraftOrderBillingInfo description: Update billing information on an existing draft order full: true --- mutation Requires one of `commerce.order:create`, `commerce.order:update`, `commerce.order:cancel`, or `commerce.order:complete` (use the scope that matches the operation). Update billing information on an existing draft order ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `orderId` `ID!` **required** * `input` `UpdateDraftOrderBillingInfoInput!` **required** * `address` `OrderAddressInput` **optional** * `companyName` `String` **optional** * `email` `String` **optional** * `firstName` `String` **optional** * `lastName` `String` **optional** * `phone` `String` **optional** ## Possible returns * `ID` `ID` — The `ID` scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `"4"`) or integer (such as `4`) input value will be accepted as an ID. # addLineItemBySkuId (https://developer.godaddy.com/en/docs/references/rest/orders/line-item/mutations/addLineItemBySkuId) --- title: addLineItemBySkuId description: Adds a line item from catalog using the skuId full: true --- mutation Requires one of `commerce.order:create`, `commerce.order:update`, `commerce.order:cancel`, or `commerce.order:complete` (use the scope that matches the operation). Adds a line item from catalog using the skuId The SKU must have at least one price. Unpriced SKUs fail with `INTERNAL_SERVER_ERROR`. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `input` `AddLineItemInput!` **required** * `fulfillmentMode` `LineItemModeInput!` **required** — Possible fulfillment modes for a line item * `orderId` `ID!` **required** — Global ID in format `Order_\` * `quantity` `Int!` **required** * `skuId` `String!` **required** * `status` `LineItemStatusInput!` **required** — Possible fulfillment statuses for a line item * `details` `AddLineItemDetailsInput` **optional** * `fulfillmentChannelId` `String` **optional** * `metafields` `[OrderMetafieldInput!]` **optional** * `name` `String` **optional** * `updateQuantity` `Boolean` **optional** — Controls whether the new quantity should be used to replace (true) or sum with the existing line item quantity (false) ## Possible returns * `LineItem` `LineItem` - `createdAt` `DateTime` **nullable** — The datetime when the line item was created in our system - `details` `LineItemDetails` **nullable** - `discounts` `[Discount!]` **nullable** — Discounts for a line item - `externalId` `String` **nullable** — Default value is undefined - `fees` `[Fee!]` **nullable** — Fees for a line item - `fulfilledAt` `DateTime` **nullable** — The datetime when the line item was fulfilled - `fulfillmentChannelId` `String` **nullable** — ID for the channel where the fulfillment of this item will occur - `fulfillmentMode` `LineItemMode` **nullable** — Possible fulfillment modes for a line item - `id` `ID!` **non-null** — Unique identifier for the line item - `metafields` `[OrderMetafield!]` **nullable** — Metafields that allow clients to store source data for a line item. For example, a `SERVICE` line item could add the booking details for the line item here - `name` `String` **nullable** — Name of the line item used for display purposes to the merchant and customer - `notes` `[Note!]` **nullable** — Notes for a line item - `orderVersion` `String` **nullable** - `productId` `String` **nullable** — Reference to a Product as defined by the Catalog (v1) service. Can be set to null. - `quantity` `Float` **nullable** — Quantity purchased by the customer. Note this could be a float value (e.g. 2.3 Kgs) - `returnedAt` `DateTime` **nullable** — The datetime when the line item was returned - `returnQuantity` `Float` **nullable** — Quantity of items returned for an order - `returnTotals` `LineItemReturnTotals` **nullable** — Grouped return totals for a line item - `serviceEndsAt` `DateTime` **nullable** — Datetime used to mark the end of service for a STAY or SERVICE line item - `serviceStartAt` `DateTime` **nullable** — Datetime used to mark the start of service for a STAY or SERVICE line item - `shipping` `ShippingInfo` **nullable** — Snapshotted shipping info associated to the line item. If not present, we assume the line item's shipping info is identical to the order's main shipping info - `skuId` `String` **nullable** — Reference to a SKU as defined by the Catalog (v2 or later) service. Can be set to null. - `status` `LineItemStatus` **nullable** — Possible fulfillment statuses for a line item - `tags` `[String!]` **nullable** — Comma delimited string of attributes for a line item. A tag should be an attribute of the line item that does not change - `taxes` `[Tax!]` **nullable** — Taxes for a line item - `totals` `LineItemTotals` **nullable** — Grouped totals for a line item - `type` `LineItemTypes` **nullable** — Type of a line item. - `unitAmount` `Money` **nullable** — Price for each unit. Stored as an integer in the currency's lowest denomination (e.g. cents for USD) - `updatedAt` `DateTime` **nullable** — The datetime when the line item was last updated in our system - `deprecatedNote` `String` **nullable** deprecated — Merchant note for a line item Deprecated: Replaced by the notes array # deleteLineItemById (https://developer.godaddy.com/en/docs/references/rest/orders/line-item/mutations/deleteLineItemById) --- title: deleteLineItemById description: Removes a line item from a draft order full: true --- mutation Requires one of `commerce.order:create`, `commerce.order:update`, `commerce.order:cancel`, or `commerce.order:complete` (use the scope that matches the operation). Removes a line item from a draft order ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `orderId` `ID!` **required** * `id` `ID!` **required** ## Possible returns * `Boolean` `Boolean` — The `Boolean` scalar type represents `true` or `false`. # updateLineItemById (https://developer.godaddy.com/en/docs/references/rest/orders/line-item/mutations/updateLineItemById) --- title: updateLineItemById description: Updates a line item in a draft order full: true --- mutation Requires one of `commerce.order:create`, `commerce.order:update`, `commerce.order:cancel`, or `commerce.order:complete` (use the scope that matches the operation). Updates a line item in a draft order ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `input` `UpdateLineItemByIdInput!` **required** * `id` `ID!` **required** — Global ID in format `LineItem_\` * `orderId` `ID!` **required** — Global ID in format `Order_\` * `details` `LineItemInputDetailsInfo` **optional** * `discounts` `[DiscountInput!]` **optional** * `externalId` `String` **optional** * `fees` `[FeeInput!]` **optional** * `fulfillmentChannelId` `String` **optional** * `fulfillmentMode` `LineItemModeInput` **optional** — Possible fulfillment modes for a line item * `metafields` `[OrderMetafieldInput!]` **optional** * `name` `String` **optional** * `notes` `[NoteInput!]` **optional** * `productId` `String` **optional** * `quantity` `Float` **optional** * `serviceEndsAt` `DateTime` **optional** * `serviceStartAt` `DateTime` **optional** * `shipping` `LineItemInputShippingInfo` **optional** * `skuId` `String` **optional** — Deprecated: This field is going to be removed. Remove and add a LineItem again instead. * `tags` `[String!]` **optional** * `taxes` `[TaxInput!]` **optional** * `totals` `TotalsInput` **optional** * `type` `LineItemTypesInput` **optional** — Possible types for a line item * `unitAmount` `MoneyInput` **optional** ## Possible returns * `LineItem` `LineItem` - `createdAt` `DateTime` **nullable** — The datetime when the line item was created in our system - `details` `LineItemDetails` **nullable** - `discounts` `[Discount!]` **nullable** — Discounts for a line item - `externalId` `String` **nullable** — Default value is undefined - `fees` `[Fee!]` **nullable** — Fees for a line item - `fulfilledAt` `DateTime` **nullable** — The datetime when the line item was fulfilled - `fulfillmentChannelId` `String` **nullable** — ID for the channel where the fulfillment of this item will occur - `fulfillmentMode` `LineItemMode` **nullable** — Possible fulfillment modes for a line item - `id` `ID!` **non-null** — Unique identifier for the line item - `metafields` `[OrderMetafield!]` **nullable** — Metafields that allow clients to store source data for a line item. For example, a `SERVICE` line item could add the booking details for the line item here - `name` `String` **nullable** — Name of the line item used for display purposes to the merchant and customer - `notes` `[Note!]` **nullable** — Notes for a line item - `orderVersion` `String` **nullable** - `productId` `String` **nullable** — Reference to a Product as defined by the Catalog (v1) service. Can be set to null. - `quantity` `Float` **nullable** — Quantity purchased by the customer. Note this could be a float value (e.g. 2.3 Kgs) - `returnedAt` `DateTime` **nullable** — The datetime when the line item was returned - `returnQuantity` `Float` **nullable** — Quantity of items returned for an order - `returnTotals` `LineItemReturnTotals` **nullable** — Grouped return totals for a line item - `serviceEndsAt` `DateTime` **nullable** — Datetime used to mark the end of service for a STAY or SERVICE line item - `serviceStartAt` `DateTime` **nullable** — Datetime used to mark the start of service for a STAY or SERVICE line item - `shipping` `ShippingInfo` **nullable** — Snapshotted shipping info associated to the line item. If not present, we assume the line item's shipping info is identical to the order's main shipping info - `skuId` `String` **nullable** — Reference to a SKU as defined by the Catalog (v2 or later) service. Can be set to null. - `status` `LineItemStatus` **nullable** — Possible fulfillment statuses for a line item - `tags` `[String!]` **nullable** — Comma delimited string of attributes for a line item. A tag should be an attribute of the line item that does not change - `taxes` `[Tax!]` **nullable** — Taxes for a line item - `totals` `LineItemTotals` **nullable** — Grouped totals for a line item - `type` `LineItemTypes` **nullable** — Type of a line item. - `unitAmount` `Money` **nullable** — Price for each unit. Stored as an integer in the currency's lowest denomination (e.g. cents for USD) - `updatedAt` `DateTime` **nullable** — The datetime when the line item was last updated in our system - `deprecatedNote` `String` **nullable** deprecated — Merchant note for a line item Deprecated: Replaced by the notes array # addOrder (https://developer.godaddy.com/en/docs/references/rest/orders/order/mutations/addOrder) --- title: addOrder description: Create a new order full: true --- mutation Requires one of `commerce.order:create`, `commerce.order:update`, `commerce.order:cancel`, or `commerce.order:complete` (use the scope that matches the operation). Create a new order ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `input` `OrderInput!` **required** * `context` `OrderContextInput!` **required** * `lineItems` `[CreateLineItemInput!]!` **required** * `processedAt` `DateTime!` **required** * `statuses` `OrderStatusesInput!` **required** * `totals` `OrderTotalsInput!` **required** * `billing` `OrderBillingInfoInput` **optional** * `canceledAt` `DateTime` **optional** * `cartId` `String` **optional** * `completedAt` `DateTime` **optional** * `customerId` `String` **optional** * `deprecatedNote` `String` **optional** — Deprecated: Replaced by the notes array * `discounts` `[DiscountInput!]` **optional** * `externalId` `String` **optional** * `fees` `[FeeInput!]` **optional** * `fulfilledAt` `DateTime` **optional** * `fulfillmentModes` `[String!]` **optional** — Automatically set based on lineItem fulfillment modes. This field is read-only. * `inventoryAction` `InventoryAction` **optional** * `metafields` `[OrderMetafieldInput!]` **optional** * `notes` `[NoteInput!]` **optional** * `number` `String` **optional** * `numberDisplay` `String` **optional** * `paidAt` `DateTime` **optional** * `refundedAt` `DateTime` **optional** * `shipping` `OrderShippingInfoInput` **optional** * `shippingLines` `[ShippingLineInput!]` **optional** * `staffUserIds` `[String!]` **optional** * `tags` `[String!]` **optional** * `taxes` `[OrderTaxInput!]` **optional** * `taxExempted` `Boolean` **optional** * `transactionIds` `[String!]` **optional** ## Possible returns * `Order` `Order` - `billing` `BillingInfo` **nullable** — Order level billing snapshot information - `canceledAt` `DateTime` **nullable** — The datetime when the order was canceled - `cartId` `String` **nullable** — ID associated with a cart. Used to link orders and carts for Inventory tracking purposes - `completedAt` `DateTime` **nullable** — The datetime when the order was completed - `context` `Context` **nullable** — Context for an order - `createdAt` `DateTime` **nullable** — The datetime when the order was created in our system - `customerId` `String` **nullable** — Reference to a Customer as defined by the Connections service - `discounts` `[Discount!]` **nullable** — Discounts for an order - `externalId` `String` **nullable** — External identifier for the order. If provided, it must be a unique identifier at a channel level - `fees` `[Fee!]` **nullable** — Fees for an order - `fulfilledAt` `DateTime` **nullable** — The datetime when the order was completely fulfilled - `fulfillmentModes` `[String!]` **nullable** — Fulfillment modes for an order - `history` `[OrderHistoryType!]` **nullable** — History for an order - `id` `ID!` **non-null** — An identifier unique to the order node. Auto-generated by the service on the fly - `inventoryAction` `InventoryAction` **nullable** — Controls inventory adjustment behavior for this order - `lineItems` `[LineItem!]` **nullable** — Line items for an order - `links` `[Links!]` **nullable** — A request-related [HATEOAS link](https://datatracker.ietf.org/doc/html/draft-handrews-json-schema-hyperschema-02). - `metafields` `[OrderMetafield!]` **nullable** — Metafields that allow clients to specify more information about the order. Attributes present in this object will not map across all channels - `notes` `[Note!]` **nullable** — Notes for an order - `number` `String` **nullable** — An identifier unique to the order. The `number` field can be used to map an existing order to an order in the Order Service. Null until the order is assigned a number (for example, DRAFT orders). - `numberDisplay` `String` **nullable** — A human readable order number handed out to customers. Used for any communications with the customer (e.g. emails, SMS, or invoices). If not provided on creation, it will match the `number` attribute - `paidAt` `DateTime` **nullable** — The datetime when the order was completely paid - `processedAt` `DateTime` **nullable** — The datetime when the order was processed. If you are importing orders from an app or another platform, then you can set `processedAt` to a datetime in the past to match when the original order was created - `refundedAt` `DateTime` **nullable** — The datetime when the order was completely refunded - `returnTotals` `OrderReturnTotals` **nullable** — Grouped totals for an order return - `shipping` `ShippingInfo` **nullable** — Order level shipping snapshot information - `shippingLines` `[ShippingLine!]` **nullable** — Shipping lines for an order - `staffUserIds` `[String!]` **nullable** — Staff users associated with the Order - `statuses` `OrderStatuses` **nullable** — Current fulfillment status, payment status, and main status for the order - `tags` `[String!]` **nullable** — Comma delimited string of tags for an order. A tag should be an attribute of the order that does not change - `taxes` `[OrderTax!]` **nullable** — Taxes for an order - `taxExempted` `Boolean` **nullable** — Details whether the order is tax exempt - `totals` `OrderTotals` **nullable** — Grouped totals for an order - `transactionIds` `[String!]` **nullable** — Transactions as defined by the Transaction Service associated with the Order - `updatedAt` `DateTime` **nullable** — The datetime when the order was last updated in our system - `deprecatedNote` `String` **nullable** deprecated — Merchant note for an Order Deprecated: Replaced by the notes array # addOrderWithId (https://developer.godaddy.com/en/docs/references/rest/orders/order/mutations/addOrderWithId) --- title: addOrderWithId description: Create a new order with a given ID full: true --- mutation Requires one of `commerce.order:create`, `commerce.order:update`, `commerce.order:cancel`, or `commerce.order:complete` (use the scope that matches the operation). Create a new order with a given ID ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `input` `AddOrderWithIdInput!` **required** * `context` `OrderContextInput!` **required** * `id` `ID!` **required** — Global ID in format `Order_\` * `lineItems` `[CreateLineItemInput!]!` **required** * `processedAt` `DateTime!` **required** * `statuses` `OrderStatusesInput!` **required** * `totals` `OrderTotalsInput!` **required** * `billing` `OrderBillingInfoInput` **optional** * `canceledAt` `DateTime` **optional** * `cartId` `String` **optional** * `completedAt` `DateTime` **optional** * `customerId` `String` **optional** * `discounts` `[DiscountInput!]` **optional** * `externalId` `String` **optional** * `fees` `[FeeInput!]` **optional** * `fulfilledAt` `DateTime` **optional** * `fulfillmentModes` `[String!]` **optional** — Automatically set based on lineItem fulfillment modes. This field is read-only. * `inventoryAction` `InventoryAction` **optional** * `metafields` `[OrderMetafieldInput!]` **optional** * `notes` `[NoteInput!]` **optional** * `number` `String` **optional** * `numberDisplay` `String` **optional** * `paidAt` `DateTime` **optional** * `refundedAt` `DateTime` **optional** * `shipping` `OrderShippingInfoInput` **optional** * `shippingLines` `[ShippingLineInput!]` **optional** * `staffUserIds` `[String!]` **optional** * `tags` `[String!]` **optional** * `taxes` `[OrderTaxInput!]` **optional** * `taxExempted` `Boolean` **optional** * `transactionIds` `[String!]` **optional** ## Possible returns * `Order` `Order` - `billing` `BillingInfo` **nullable** — Order level billing snapshot information - `canceledAt` `DateTime` **nullable** — The datetime when the order was canceled - `cartId` `String` **nullable** — ID associated with a cart. Used to link orders and carts for Inventory tracking purposes - `completedAt` `DateTime` **nullable** — The datetime when the order was completed - `context` `Context` **nullable** — Context for an order - `createdAt` `DateTime` **nullable** — The datetime when the order was created in our system - `customerId` `String` **nullable** — Reference to a Customer as defined by the Connections service - `discounts` `[Discount!]` **nullable** — Discounts for an order - `externalId` `String` **nullable** — External identifier for the order. If provided, it must be a unique identifier at a channel level - `fees` `[Fee!]` **nullable** — Fees for an order - `fulfilledAt` `DateTime` **nullable** — The datetime when the order was completely fulfilled - `fulfillmentModes` `[String!]` **nullable** — Fulfillment modes for an order - `history` `[OrderHistoryType!]` **nullable** — History for an order - `id` `ID!` **non-null** — An identifier unique to the order node. Auto-generated by the service on the fly - `inventoryAction` `InventoryAction` **nullable** — Controls inventory adjustment behavior for this order - `lineItems` `[LineItem!]` **nullable** — Line items for an order - `links` `[Links!]` **nullable** — A request-related [HATEOAS link](https://datatracker.ietf.org/doc/html/draft-handrews-json-schema-hyperschema-02). - `metafields` `[OrderMetafield!]` **nullable** — Metafields that allow clients to specify more information about the order. Attributes present in this object will not map across all channels - `notes` `[Note!]` **nullable** — Notes for an order - `number` `String` **nullable** — An identifier unique to the order. The `number` field can be used to map an existing order to an order in the Order Service. Null until the order is assigned a number (for example, DRAFT orders). - `numberDisplay` `String` **nullable** — A human readable order number handed out to customers. Used for any communications with the customer (e.g. emails, SMS, or invoices). If not provided on creation, it will match the `number` attribute - `paidAt` `DateTime` **nullable** — The datetime when the order was completely paid - `processedAt` `DateTime` **nullable** — The datetime when the order was processed. If you are importing orders from an app or another platform, then you can set `processedAt` to a datetime in the past to match when the original order was created - `refundedAt` `DateTime` **nullable** — The datetime when the order was completely refunded - `returnTotals` `OrderReturnTotals` **nullable** — Grouped totals for an order return - `shipping` `ShippingInfo` **nullable** — Order level shipping snapshot information - `shippingLines` `[ShippingLine!]` **nullable** — Shipping lines for an order - `staffUserIds` `[String!]` **nullable** — Staff users associated with the Order - `statuses` `OrderStatuses` **nullable** — Current fulfillment status, payment status, and main status for the order - `tags` `[String!]` **nullable** — Comma delimited string of tags for an order. A tag should be an attribute of the order that does not change - `taxes` `[OrderTax!]` **nullable** — Taxes for an order - `taxExempted` `Boolean` **nullable** — Details whether the order is tax exempt - `totals` `OrderTotals` **nullable** — Grouped totals for an order - `transactionIds` `[String!]` **nullable** — Transactions as defined by the Transaction Service associated with the Order - `updatedAt` `DateTime` **nullable** — The datetime when the order was last updated in our system - `deprecatedNote` `String` **nullable** deprecated — Merchant note for an Order Deprecated: Replaced by the notes array # cancelOrder (https://developer.godaddy.com/en/docs/references/rest/orders/order/mutations/cancelOrder) --- title: cancelOrder description: >- Cancel an existing order. Only an `OPEN` order can be marked as canceled. Set `force: true` to cancel a `COMPLETED` order. full: true --- mutation Requires one of `commerce.order:create`, `commerce.order:update`, `commerce.order:cancel`, or `commerce.order:complete` (use the scope that matches the operation). Cancel an existing order. Only an `OPEN` order can be marked as canceled. Set `force: true` to cancel a `COMPLETED` order. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `ID!` **required** * `force` `Boolean` **optional** Default: `false`. ## Possible returns * `Order` `Order` - `billing` `BillingInfo` **nullable** — Order level billing snapshot information - `canceledAt` `DateTime` **nullable** — The datetime when the order was canceled - `cartId` `String` **nullable** — ID associated with a cart. Used to link orders and carts for Inventory tracking purposes - `completedAt` `DateTime` **nullable** — The datetime when the order was completed - `context` `Context` **nullable** — Context for an order - `createdAt` `DateTime` **nullable** — The datetime when the order was created in our system - `customerId` `String` **nullable** — Reference to a Customer as defined by the Connections service - `discounts` `[Discount!]` **nullable** — Discounts for an order - `externalId` `String` **nullable** — External identifier for the order. If provided, it must be a unique identifier at a channel level - `fees` `[Fee!]` **nullable** — Fees for an order - `fulfilledAt` `DateTime` **nullable** — The datetime when the order was completely fulfilled - `fulfillmentModes` `[String!]` **nullable** — Fulfillment modes for an order - `history` `[OrderHistoryType!]` **nullable** — History for an order - `id` `ID!` **non-null** — An identifier unique to the order node. Auto-generated by the service on the fly - `inventoryAction` `InventoryAction` **nullable** — Controls inventory adjustment behavior for this order - `lineItems` `[LineItem!]` **nullable** — Line items for an order - `links` `[Links!]` **nullable** — A request-related [HATEOAS link](https://datatracker.ietf.org/doc/html/draft-handrews-json-schema-hyperschema-02). - `metafields` `[OrderMetafield!]` **nullable** — Metafields that allow clients to specify more information about the order. Attributes present in this object will not map across all channels - `notes` `[Note!]` **nullable** — Notes for an order - `number` `String` **nullable** — An identifier unique to the order. The `number` field can be used to map an existing order to an order in the Order Service. Null until the order is assigned a number (for example, DRAFT orders). - `numberDisplay` `String` **nullable** — A human readable order number handed out to customers. Used for any communications with the customer (e.g. emails, SMS, or invoices). If not provided on creation, it will match the `number` attribute - `paidAt` `DateTime` **nullable** — The datetime when the order was completely paid - `processedAt` `DateTime` **nullable** — The datetime when the order was processed. If you are importing orders from an app or another platform, then you can set `processedAt` to a datetime in the past to match when the original order was created - `refundedAt` `DateTime` **nullable** — The datetime when the order was completely refunded - `returnTotals` `OrderReturnTotals` **nullable** — Grouped totals for an order return - `shipping` `ShippingInfo` **nullable** — Order level shipping snapshot information - `shippingLines` `[ShippingLine!]` **nullable** — Shipping lines for an order - `staffUserIds` `[String!]` **nullable** — Staff users associated with the Order - `statuses` `OrderStatuses` **nullable** — Current fulfillment status, payment status, and main status for the order - `tags` `[String!]` **nullable** — Comma delimited string of tags for an order. A tag should be an attribute of the order that does not change - `taxes` `[OrderTax!]` **nullable** — Taxes for an order - `taxExempted` `Boolean` **nullable** — Details whether the order is tax exempt - `totals` `OrderTotals` **nullable** — Grouped totals for an order - `transactionIds` `[String!]` **nullable** — Transactions as defined by the Transaction Service associated with the Order - `updatedAt` `DateTime` **nullable** — The datetime when the order was last updated in our system - `deprecatedNote` `String` **nullable** deprecated — Merchant note for an Order Deprecated: Replaced by the notes array # completeOrder (https://developer.godaddy.com/en/docs/references/rest/orders/order/mutations/completeOrder) --- title: completeOrder description: Complete an existing order. Only an `OPEN` order can be marked as complete full: true --- mutation Requires one of `commerce.order:create`, `commerce.order:update`, `commerce.order:cancel`, or `commerce.order:complete` (use the scope that matches the operation). Complete an existing order. Only an `OPEN` order can be marked as complete ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `ID!` **required** ## Possible returns * `Order` `Order` - `billing` `BillingInfo` **nullable** — Order level billing snapshot information - `canceledAt` `DateTime` **nullable** — The datetime when the order was canceled - `cartId` `String` **nullable** — ID associated with a cart. Used to link orders and carts for Inventory tracking purposes - `completedAt` `DateTime` **nullable** — The datetime when the order was completed - `context` `Context` **nullable** — Context for an order - `createdAt` `DateTime` **nullable** — The datetime when the order was created in our system - `customerId` `String` **nullable** — Reference to a Customer as defined by the Connections service - `discounts` `[Discount!]` **nullable** — Discounts for an order - `externalId` `String` **nullable** — External identifier for the order. If provided, it must be a unique identifier at a channel level - `fees` `[Fee!]` **nullable** — Fees for an order - `fulfilledAt` `DateTime` **nullable** — The datetime when the order was completely fulfilled - `fulfillmentModes` `[String!]` **nullable** — Fulfillment modes for an order - `history` `[OrderHistoryType!]` **nullable** — History for an order - `id` `ID!` **non-null** — An identifier unique to the order node. Auto-generated by the service on the fly - `inventoryAction` `InventoryAction` **nullable** — Controls inventory adjustment behavior for this order - `lineItems` `[LineItem!]` **nullable** — Line items for an order - `links` `[Links!]` **nullable** — A request-related [HATEOAS link](https://datatracker.ietf.org/doc/html/draft-handrews-json-schema-hyperschema-02). - `metafields` `[OrderMetafield!]` **nullable** — Metafields that allow clients to specify more information about the order. Attributes present in this object will not map across all channels - `notes` `[Note!]` **nullable** — Notes for an order - `number` `String` **nullable** — An identifier unique to the order. The `number` field can be used to map an existing order to an order in the Order Service. Null until the order is assigned a number (for example, DRAFT orders). - `numberDisplay` `String` **nullable** — A human readable order number handed out to customers. Used for any communications with the customer (e.g. emails, SMS, or invoices). If not provided on creation, it will match the `number` attribute - `paidAt` `DateTime` **nullable** — The datetime when the order was completely paid - `processedAt` `DateTime` **nullable** — The datetime when the order was processed. If you are importing orders from an app or another platform, then you can set `processedAt` to a datetime in the past to match when the original order was created - `refundedAt` `DateTime` **nullable** — The datetime when the order was completely refunded - `returnTotals` `OrderReturnTotals` **nullable** — Grouped totals for an order return - `shipping` `ShippingInfo` **nullable** — Order level shipping snapshot information - `shippingLines` `[ShippingLine!]` **nullable** — Shipping lines for an order - `staffUserIds` `[String!]` **nullable** — Staff users associated with the Order - `statuses` `OrderStatuses` **nullable** — Current fulfillment status, payment status, and main status for the order - `tags` `[String!]` **nullable** — Comma delimited string of tags for an order. A tag should be an attribute of the order that does not change - `taxes` `[OrderTax!]` **nullable** — Taxes for an order - `taxExempted` `Boolean` **nullable** — Details whether the order is tax exempt - `totals` `OrderTotals` **nullable** — Grouped totals for an order - `transactionIds` `[String!]` **nullable** — Transactions as defined by the Transaction Service associated with the Order - `updatedAt` `DateTime` **nullable** — The datetime when the order was last updated in our system - `deprecatedNote` `String` **nullable** deprecated — Merchant note for an Order Deprecated: Replaced by the notes array # openOrder (https://developer.godaddy.com/en/docs/references/rest/orders/order/mutations/openOrder) --- title: openOrder description: >- Converts an existing DRAFT order to OPEN status. Only a DRAFT order can be converted to OPEN. full: true --- mutation Requires one of `commerce.order:create`, `commerce.order:update`, `commerce.order:cancel`, or `commerce.order:complete` (use the scope that matches the operation). Converts an existing DRAFT order to OPEN status. Only a DRAFT order can be converted to OPEN. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `ID!` **required** ## Possible returns * `Order` `Order` - `billing` `BillingInfo` **nullable** — Order level billing snapshot information - `canceledAt` `DateTime` **nullable** — The datetime when the order was canceled - `cartId` `String` **nullable** — ID associated with a cart. Used to link orders and carts for Inventory tracking purposes - `completedAt` `DateTime` **nullable** — The datetime when the order was completed - `context` `Context` **nullable** — Context for an order - `createdAt` `DateTime` **nullable** — The datetime when the order was created in our system - `customerId` `String` **nullable** — Reference to a Customer as defined by the Connections service - `discounts` `[Discount!]` **nullable** — Discounts for an order - `externalId` `String` **nullable** — External identifier for the order. If provided, it must be a unique identifier at a channel level - `fees` `[Fee!]` **nullable** — Fees for an order - `fulfilledAt` `DateTime` **nullable** — The datetime when the order was completely fulfilled - `fulfillmentModes` `[String!]` **nullable** — Fulfillment modes for an order - `history` `[OrderHistoryType!]` **nullable** — History for an order - `id` `ID!` **non-null** — An identifier unique to the order node. Auto-generated by the service on the fly - `inventoryAction` `InventoryAction` **nullable** — Controls inventory adjustment behavior for this order - `lineItems` `[LineItem!]` **nullable** — Line items for an order - `links` `[Links!]` **nullable** — A request-related [HATEOAS link](https://datatracker.ietf.org/doc/html/draft-handrews-json-schema-hyperschema-02). - `metafields` `[OrderMetafield!]` **nullable** — Metafields that allow clients to specify more information about the order. Attributes present in this object will not map across all channels - `notes` `[Note!]` **nullable** — Notes for an order - `number` `String` **nullable** — An identifier unique to the order. The `number` field can be used to map an existing order to an order in the Order Service. Null until the order is assigned a number (for example, DRAFT orders). - `numberDisplay` `String` **nullable** — A human readable order number handed out to customers. Used for any communications with the customer (e.g. emails, SMS, or invoices). If not provided on creation, it will match the `number` attribute - `paidAt` `DateTime` **nullable** — The datetime when the order was completely paid - `processedAt` `DateTime` **nullable** — The datetime when the order was processed. If you are importing orders from an app or another platform, then you can set `processedAt` to a datetime in the past to match when the original order was created - `refundedAt` `DateTime` **nullable** — The datetime when the order was completely refunded - `returnTotals` `OrderReturnTotals` **nullable** — Grouped totals for an order return - `shipping` `ShippingInfo` **nullable** — Order level shipping snapshot information - `shippingLines` `[ShippingLine!]` **nullable** — Shipping lines for an order - `staffUserIds` `[String!]` **nullable** — Staff users associated with the Order - `statuses` `OrderStatuses` **nullable** — Current fulfillment status, payment status, and main status for the order - `tags` `[String!]` **nullable** — Comma delimited string of tags for an order. A tag should be an attribute of the order that does not change - `taxes` `[OrderTax!]` **nullable** — Taxes for an order - `taxExempted` `Boolean` **nullable** — Details whether the order is tax exempt - `totals` `OrderTotals` **nullable** — Grouped totals for an order - `transactionIds` `[String!]` **nullable** — Transactions as defined by the Transaction Service associated with the Order - `updatedAt` `DateTime` **nullable** — The datetime when the order was last updated in our system - `deprecatedNote` `String` **nullable** deprecated — Merchant note for an Order Deprecated: Replaced by the notes array # refundOrder (https://developer.godaddy.com/en/docs/references/rest/orders/order/mutations/refundOrder) --- title: refundOrder description: Refund an existing order. Only non-draft orders can be marked as refunded full: true --- mutation Requires one of `commerce.order:create`, `commerce.order:update`, `commerce.order:cancel`, or `commerce.order:complete` (use the scope that matches the operation). Refund an existing order. Only non-draft orders can be marked as refunded ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `input` `RefundOrderInput!` **required** * `orderId` `ID!` **required** — Global ID in format `Order_\` * `refundedAt` `DateTime` **optional** ## Possible returns * `Order` `Order` - `billing` `BillingInfo` **nullable** — Order level billing snapshot information - `canceledAt` `DateTime` **nullable** — The datetime when the order was canceled - `cartId` `String` **nullable** — ID associated with a cart. Used to link orders and carts for Inventory tracking purposes - `completedAt` `DateTime` **nullable** — The datetime when the order was completed - `context` `Context` **nullable** — Context for an order - `createdAt` `DateTime` **nullable** — The datetime when the order was created in our system - `customerId` `String` **nullable** — Reference to a Customer as defined by the Connections service - `discounts` `[Discount!]` **nullable** — Discounts for an order - `externalId` `String` **nullable** — External identifier for the order. If provided, it must be a unique identifier at a channel level - `fees` `[Fee!]` **nullable** — Fees for an order - `fulfilledAt` `DateTime` **nullable** — The datetime when the order was completely fulfilled - `fulfillmentModes` `[String!]` **nullable** — Fulfillment modes for an order - `history` `[OrderHistoryType!]` **nullable** — History for an order - `id` `ID!` **non-null** — An identifier unique to the order node. Auto-generated by the service on the fly - `inventoryAction` `InventoryAction` **nullable** — Controls inventory adjustment behavior for this order - `lineItems` `[LineItem!]` **nullable** — Line items for an order - `links` `[Links!]` **nullable** — A request-related [HATEOAS link](https://datatracker.ietf.org/doc/html/draft-handrews-json-schema-hyperschema-02). - `metafields` `[OrderMetafield!]` **nullable** — Metafields that allow clients to specify more information about the order. Attributes present in this object will not map across all channels - `notes` `[Note!]` **nullable** — Notes for an order - `number` `String` **nullable** — An identifier unique to the order. The `number` field can be used to map an existing order to an order in the Order Service. Null until the order is assigned a number (for example, DRAFT orders). - `numberDisplay` `String` **nullable** — A human readable order number handed out to customers. Used for any communications with the customer (e.g. emails, SMS, or invoices). If not provided on creation, it will match the `number` attribute - `paidAt` `DateTime` **nullable** — The datetime when the order was completely paid - `processedAt` `DateTime` **nullable** — The datetime when the order was processed. If you are importing orders from an app or another platform, then you can set `processedAt` to a datetime in the past to match when the original order was created - `refundedAt` `DateTime` **nullable** — The datetime when the order was completely refunded - `returnTotals` `OrderReturnTotals` **nullable** — Grouped totals for an order return - `shipping` `ShippingInfo` **nullable** — Order level shipping snapshot information - `shippingLines` `[ShippingLine!]` **nullable** — Shipping lines for an order - `staffUserIds` `[String!]` **nullable** — Staff users associated with the Order - `statuses` `OrderStatuses` **nullable** — Current fulfillment status, payment status, and main status for the order - `tags` `[String!]` **nullable** — Comma delimited string of tags for an order. A tag should be an attribute of the order that does not change - `taxes` `[OrderTax!]` **nullable** — Taxes for an order - `taxExempted` `Boolean` **nullable** — Details whether the order is tax exempt - `totals` `OrderTotals` **nullable** — Grouped totals for an order - `transactionIds` `[String!]` **nullable** — Transactions as defined by the Transaction Service associated with the Order - `updatedAt` `DateTime` **nullable** — The datetime when the order was last updated in our system - `deprecatedNote` `String` **nullable** deprecated — Merchant note for an Order Deprecated: Replaced by the notes array # resendOrderConfirmation (https://developer.godaddy.com/en/docs/references/rest/orders/order/mutations/resendOrderConfirmation) --- title: resendOrderConfirmation description: Resend order confirmation for an existing order. full: true --- mutation Requires one of `commerce.order:create`, `commerce.order:update`, `commerce.order:cancel`, or `commerce.order:complete` (use the scope that matches the operation). Resend order confirmation for an existing order. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `ID!` **required** ## Possible returns * `Order` `Order` - `billing` `BillingInfo` **nullable** — Order level billing snapshot information - `canceledAt` `DateTime` **nullable** — The datetime when the order was canceled - `cartId` `String` **nullable** — ID associated with a cart. Used to link orders and carts for Inventory tracking purposes - `completedAt` `DateTime` **nullable** — The datetime when the order was completed - `context` `Context` **nullable** — Context for an order - `createdAt` `DateTime` **nullable** — The datetime when the order was created in our system - `customerId` `String` **nullable** — Reference to a Customer as defined by the Connections service - `discounts` `[Discount!]` **nullable** — Discounts for an order - `externalId` `String` **nullable** — External identifier for the order. If provided, it must be a unique identifier at a channel level - `fees` `[Fee!]` **nullable** — Fees for an order - `fulfilledAt` `DateTime` **nullable** — The datetime when the order was completely fulfilled - `fulfillmentModes` `[String!]` **nullable** — Fulfillment modes for an order - `history` `[OrderHistoryType!]` **nullable** — History for an order - `id` `ID!` **non-null** — An identifier unique to the order node. Auto-generated by the service on the fly - `inventoryAction` `InventoryAction` **nullable** — Controls inventory adjustment behavior for this order - `lineItems` `[LineItem!]` **nullable** — Line items for an order - `links` `[Links!]` **nullable** — A request-related [HATEOAS link](https://datatracker.ietf.org/doc/html/draft-handrews-json-schema-hyperschema-02). - `metafields` `[OrderMetafield!]` **nullable** — Metafields that allow clients to specify more information about the order. Attributes present in this object will not map across all channels - `notes` `[Note!]` **nullable** — Notes for an order - `number` `String` **nullable** — An identifier unique to the order. The `number` field can be used to map an existing order to an order in the Order Service. Null until the order is assigned a number (for example, DRAFT orders). - `numberDisplay` `String` **nullable** — A human readable order number handed out to customers. Used for any communications with the customer (e.g. emails, SMS, or invoices). If not provided on creation, it will match the `number` attribute - `paidAt` `DateTime` **nullable** — The datetime when the order was completely paid - `processedAt` `DateTime` **nullable** — The datetime when the order was processed. If you are importing orders from an app or another platform, then you can set `processedAt` to a datetime in the past to match when the original order was created - `refundedAt` `DateTime` **nullable** — The datetime when the order was completely refunded - `returnTotals` `OrderReturnTotals` **nullable** — Grouped totals for an order return - `shipping` `ShippingInfo` **nullable** — Order level shipping snapshot information - `shippingLines` `[ShippingLine!]` **nullable** — Shipping lines for an order - `staffUserIds` `[String!]` **nullable** — Staff users associated with the Order - `statuses` `OrderStatuses` **nullable** — Current fulfillment status, payment status, and main status for the order - `tags` `[String!]` **nullable** — Comma delimited string of tags for an order. A tag should be an attribute of the order that does not change - `taxes` `[OrderTax!]` **nullable** — Taxes for an order - `taxExempted` `Boolean` **nullable** — Details whether the order is tax exempt - `totals` `OrderTotals` **nullable** — Grouped totals for an order - `transactionIds` `[String!]` **nullable** — Transactions as defined by the Transaction Service associated with the Order - `updatedAt` `DateTime` **nullable** — The datetime when the order was last updated in our system - `deprecatedNote` `String` **nullable** deprecated — Merchant note for an Order Deprecated: Replaced by the notes array # updateOrder (https://developer.godaddy.com/en/docs/references/rest/orders/order/mutations/updateOrder) --- title: updateOrder description: Update an existing order full: true --- mutation Requires one of `commerce.order:create`, `commerce.order:update`, `commerce.order:cancel`, or `commerce.order:complete` (use the scope that matches the operation). Update an existing order ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `input` `UpdateOrderInput!` **required** * `context` `OrderContextInputUpdate!` **required** * `id` `ID!` **required** * `billing` `OrderBillingInfoInput` **optional** * `canceledAt` `DateTime` **optional** * `completedAt` `DateTime` **optional** * `customerId` `String` **optional** * `deprecatedNote` `String` **optional** — Deprecated: Replaced by the notes array * `discounts` `[UpdateDiscountInput!]` **optional** * `fees` `[UpdateFeeInput!]` **optional** * `fulfilledAt` `DateTime` **optional** * `fulfillmentModes` `[String!]` **optional** — Automatically set based on lineItem fulfillment modes. This field is read-only. * `lineItems` `[UpdateLineItemInput!]` **optional** * `metafields` `[OrderMetafieldInput!]` **optional** * `notes` `[UpdateNoteInput!]` **optional** * `number` `String` **optional** * `numberDisplay` `String` **optional** * `paidAt` `DateTime` **optional** * `processedAt` `DateTime` **optional** * `refundedAt` `DateTime` **optional** * `shipping` `OrderShippingInfoInput` **optional** * `shippingLines` `[UpdateShippingLineInput!]` **optional** * `staffUserIds` `[String!]` **optional** * `statuses` `OrderStatusesInputUpdate` **optional** * `tags` `[String!]` **optional** * `taxes` `[UpdateOrderTaxInput!]` **optional** * `totals` `OrderTotalsInput` **optional** * `transactionIds` `[String!]` **optional** ## Possible returns * `Order` `Order` - `billing` `BillingInfo` **nullable** — Order level billing snapshot information - `canceledAt` `DateTime` **nullable** — The datetime when the order was canceled - `cartId` `String` **nullable** — ID associated with a cart. Used to link orders and carts for Inventory tracking purposes - `completedAt` `DateTime` **nullable** — The datetime when the order was completed - `context` `Context` **nullable** — Context for an order - `createdAt` `DateTime` **nullable** — The datetime when the order was created in our system - `customerId` `String` **nullable** — Reference to a Customer as defined by the Connections service - `discounts` `[Discount!]` **nullable** — Discounts for an order - `externalId` `String` **nullable** — External identifier for the order. If provided, it must be a unique identifier at a channel level - `fees` `[Fee!]` **nullable** — Fees for an order - `fulfilledAt` `DateTime` **nullable** — The datetime when the order was completely fulfilled - `fulfillmentModes` `[String!]` **nullable** — Fulfillment modes for an order - `history` `[OrderHistoryType!]` **nullable** — History for an order - `id` `ID!` **non-null** — An identifier unique to the order node. Auto-generated by the service on the fly - `inventoryAction` `InventoryAction` **nullable** — Controls inventory adjustment behavior for this order - `lineItems` `[LineItem!]` **nullable** — Line items for an order - `links` `[Links!]` **nullable** — A request-related [HATEOAS link](https://datatracker.ietf.org/doc/html/draft-handrews-json-schema-hyperschema-02). - `metafields` `[OrderMetafield!]` **nullable** — Metafields that allow clients to specify more information about the order. Attributes present in this object will not map across all channels - `notes` `[Note!]` **nullable** — Notes for an order - `number` `String` **nullable** — An identifier unique to the order. The `number` field can be used to map an existing order to an order in the Order Service. Null until the order is assigned a number (for example, DRAFT orders). - `numberDisplay` `String` **nullable** — A human readable order number handed out to customers. Used for any communications with the customer (e.g. emails, SMS, or invoices). If not provided on creation, it will match the `number` attribute - `paidAt` `DateTime` **nullable** — The datetime when the order was completely paid - `processedAt` `DateTime` **nullable** — The datetime when the order was processed. If you are importing orders from an app or another platform, then you can set `processedAt` to a datetime in the past to match when the original order was created - `refundedAt` `DateTime` **nullable** — The datetime when the order was completely refunded - `returnTotals` `OrderReturnTotals` **nullable** — Grouped totals for an order return - `shipping` `ShippingInfo` **nullable** — Order level shipping snapshot information - `shippingLines` `[ShippingLine!]` **nullable** — Shipping lines for an order - `staffUserIds` `[String!]` **nullable** — Staff users associated with the Order - `statuses` `OrderStatuses` **nullable** — Current fulfillment status, payment status, and main status for the order - `tags` `[String!]` **nullable** — Comma delimited string of tags for an order. A tag should be an attribute of the order that does not change - `taxes` `[OrderTax!]` **nullable** — Taxes for an order - `taxExempted` `Boolean` **nullable** — Details whether the order is tax exempt - `totals` `OrderTotals` **nullable** — Grouped totals for an order - `transactionIds` `[String!]` **nullable** — Transactions as defined by the Transaction Service associated with the Order - `updatedAt` `DateTime` **nullable** — The datetime when the order was last updated in our system - `deprecatedNote` `String` **nullable** deprecated — Merchant note for an Order Deprecated: Replaced by the notes array # archivedOrderById (https://developer.godaddy.com/en/docs/references/rest/orders/order/queries/archivedOrderById) --- title: archivedOrderById description: 'Deprecated: We no longer archive orders' full: true --- query Requires `commerce.order:read`. Deprecated: We no longer archive orders Deprecated: We no longer archive orders ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `ID!` **required** ## Possible returns * `Order` `Order` - `billing` `BillingInfo` **nullable** — Order level billing snapshot information - `canceledAt` `DateTime` **nullable** — The datetime when the order was canceled - `cartId` `String` **nullable** — ID associated with a cart. Used to link orders and carts for Inventory tracking purposes - `completedAt` `DateTime` **nullable** — The datetime when the order was completed - `context` `Context` **nullable** — Context for an order - `createdAt` `DateTime` **nullable** — The datetime when the order was created in our system - `customerId` `String` **nullable** — Reference to a Customer as defined by the Connections service - `discounts` `[Discount!]` **nullable** — Discounts for an order - `externalId` `String` **nullable** — External identifier for the order. If provided, it must be a unique identifier at a channel level - `fees` `[Fee!]` **nullable** — Fees for an order - `fulfilledAt` `DateTime` **nullable** — The datetime when the order was completely fulfilled - `fulfillmentModes` `[String!]` **nullable** — Fulfillment modes for an order - `history` `[OrderHistoryType!]` **nullable** — History for an order - `id` `ID!` **non-null** — An identifier unique to the order node. Auto-generated by the service on the fly - `inventoryAction` `InventoryAction` **nullable** — Controls inventory adjustment behavior for this order - `lineItems` `[LineItem!]` **nullable** — Line items for an order - `links` `[Links!]` **nullable** — A request-related [HATEOAS link](https://datatracker.ietf.org/doc/html/draft-handrews-json-schema-hyperschema-02). - `metafields` `[OrderMetafield!]` **nullable** — Metafields that allow clients to specify more information about the order. Attributes present in this object will not map across all channels - `notes` `[Note!]` **nullable** — Notes for an order - `number` `String` **nullable** — An identifier unique to the order. The `number` field can be used to map an existing order to an order in the Order Service. Null until the order is assigned a number (for example, DRAFT orders). - `numberDisplay` `String` **nullable** — A human readable order number handed out to customers. Used for any communications with the customer (e.g. emails, SMS, or invoices). If not provided on creation, it will match the `number` attribute - `paidAt` `DateTime` **nullable** — The datetime when the order was completely paid - `processedAt` `DateTime` **nullable** — The datetime when the order was processed. If you are importing orders from an app or another platform, then you can set `processedAt` to a datetime in the past to match when the original order was created - `refundedAt` `DateTime` **nullable** — The datetime when the order was completely refunded - `returnTotals` `OrderReturnTotals` **nullable** — Grouped totals for an order return - `shipping` `ShippingInfo` **nullable** — Order level shipping snapshot information - `shippingLines` `[ShippingLine!]` **nullable** — Shipping lines for an order - `staffUserIds` `[String!]` **nullable** — Staff users associated with the Order - `statuses` `OrderStatuses` **nullable** — Current fulfillment status, payment status, and main status for the order - `tags` `[String!]` **nullable** — Comma delimited string of tags for an order. A tag should be an attribute of the order that does not change - `taxes` `[OrderTax!]` **nullable** — Taxes for an order - `taxExempted` `Boolean` **nullable** — Details whether the order is tax exempt - `totals` `OrderTotals` **nullable** — Grouped totals for an order - `transactionIds` `[String!]` **nullable** — Transactions as defined by the Transaction Service associated with the Order - `updatedAt` `DateTime` **nullable** — The datetime when the order was last updated in our system - `deprecatedNote` `String` **nullable** deprecated — Merchant note for an Order Deprecated: Replaced by the notes array # archivedOrders (https://developer.godaddy.com/en/docs/references/rest/orders/order/queries/archivedOrders) --- title: archivedOrders description: 'Deprecated: We no longer archive orders' full: true --- query Requires `commerce.order:read`. Deprecated: We no longer archive orders Deprecated: We no longer archive orders ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `sortOrder` `SortOrder` **optional** Default: `"ASC"`. * `before` `ID` **optional** — Look for entries before that cursor * `after` `ID` **optional** — Look for entries after that cursor * `first` `Int` **optional** — Look for the first entries (paginate forward) * `last` `Int` **optional** — Look for the last entries (paginate backward) ## Possible returns * `QueryArchivedOrdersConnection` `QueryArchivedOrdersConnection` - `edges` `[QueryArchivedOrdersConnectionEdge]` **nullable** - `pageInfo` `PageInfo!` **non-null** # archivedOrdersByIds (https://developer.godaddy.com/en/docs/references/rest/orders/order/queries/archivedOrdersByIds) --- title: archivedOrdersByIds description: 'Deprecated: We no longer archive orders' full: true --- query Requires `commerce.order:read`. Deprecated: We no longer archive orders Deprecated: We no longer archive orders ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `ids` `[ID!]!` **required** ## Possible returns * `Order` `[Order!]` - `billing` `BillingInfo` **nullable** — Order level billing snapshot information - `canceledAt` `DateTime` **nullable** — The datetime when the order was canceled - `cartId` `String` **nullable** — ID associated with a cart. Used to link orders and carts for Inventory tracking purposes - `completedAt` `DateTime` **nullable** — The datetime when the order was completed - `context` `Context` **nullable** — Context for an order - `createdAt` `DateTime` **nullable** — The datetime when the order was created in our system - `customerId` `String` **nullable** — Reference to a Customer as defined by the Connections service - `discounts` `[Discount!]` **nullable** — Discounts for an order - `externalId` `String` **nullable** — External identifier for the order. If provided, it must be a unique identifier at a channel level - `fees` `[Fee!]` **nullable** — Fees for an order - `fulfilledAt` `DateTime` **nullable** — The datetime when the order was completely fulfilled - `fulfillmentModes` `[String!]` **nullable** — Fulfillment modes for an order - `history` `[OrderHistoryType!]` **nullable** — History for an order - `id` `ID!` **non-null** — An identifier unique to the order node. Auto-generated by the service on the fly - `inventoryAction` `InventoryAction` **nullable** — Controls inventory adjustment behavior for this order - `lineItems` `[LineItem!]` **nullable** — Line items for an order - `links` `[Links!]` **nullable** — A request-related [HATEOAS link](https://datatracker.ietf.org/doc/html/draft-handrews-json-schema-hyperschema-02). - `metafields` `[OrderMetafield!]` **nullable** — Metafields that allow clients to specify more information about the order. Attributes present in this object will not map across all channels - `notes` `[Note!]` **nullable** — Notes for an order - `number` `String` **nullable** — An identifier unique to the order. The `number` field can be used to map an existing order to an order in the Order Service. Null until the order is assigned a number (for example, DRAFT orders). - `numberDisplay` `String` **nullable** — A human readable order number handed out to customers. Used for any communications with the customer (e.g. emails, SMS, or invoices). If not provided on creation, it will match the `number` attribute - `paidAt` `DateTime` **nullable** — The datetime when the order was completely paid - `processedAt` `DateTime` **nullable** — The datetime when the order was processed. If you are importing orders from an app or another platform, then you can set `processedAt` to a datetime in the past to match when the original order was created - `refundedAt` `DateTime` **nullable** — The datetime when the order was completely refunded - `returnTotals` `OrderReturnTotals` **nullable** — Grouped totals for an order return - `shipping` `ShippingInfo` **nullable** — Order level shipping snapshot information - `shippingLines` `[ShippingLine!]` **nullable** — Shipping lines for an order - `staffUserIds` `[String!]` **nullable** — Staff users associated with the Order - `statuses` `OrderStatuses` **nullable** — Current fulfillment status, payment status, and main status for the order - `tags` `[String!]` **nullable** — Comma delimited string of tags for an order. A tag should be an attribute of the order that does not change - `taxes` `[OrderTax!]` **nullable** — Taxes for an order - `taxExempted` `Boolean` **nullable** — Details whether the order is tax exempt - `totals` `OrderTotals` **nullable** — Grouped totals for an order - `transactionIds` `[String!]` **nullable** — Transactions as defined by the Transaction Service associated with the Order - `updatedAt` `DateTime` **nullable** — The datetime when the order was last updated in our system - `deprecatedNote` `String` **nullable** deprecated — Merchant note for an Order Deprecated: Replaced by the notes array # filterOrders (https://developer.godaddy.com/en/docs/references/rest/orders/order/queries/filterOrders) --- title: filterOrders description: Query `filterOrders` on the order subgraph (Order). full: true --- query Requires `commerce.order:read`. Query `filterOrders` on the order subgraph (Order). ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `processedAtStart` `DateTime` **optional** * `processedAtEnd` `DateTime` **optional** * `updatedAtStart` `DateTime` **optional** * `updatedAtEnd` `DateTime` **optional** * `number` `String` **optional** * `status` `[FilterOrdersStatus!]` **optional** * `paymentStatus` `[FilterOrdersPaymentStatus!]` **optional** - `fulfillmentMode` `[FilterOrdersFulfillmentMode!]` **optional** - `channelId` `[String!]` **optional** - `tags` `[String!]` **optional** - `sortBy` `FilterOrdersSortBy` **optional** Default: `"processedAt"`. - `sortOrder` `SortOrder` **optional** Default: `"ASC"`. - `email` `[String!]` **optional** - `name` `String` **optional** - `staffUserIds` `[String!]` **optional** - `externalIdType` `String` **optional** — ExternalId Type. Must be used along with externalIdValue - `externalIdValue` `String` **optional** — ExternalId Value. Must be used along with externalIdType - `customerId` `String` **optional** - `excludeTags` `[String!]` **optional** Default: `["standalone-transaction"]`. — Tags to exclude from the search. - `before` `ID` **optional** — Look for entries before that cursor - `after` `ID` **optional** — Look for entries after that cursor - `first` `Int` **optional** — Look for the first entries (paginate forward) - `last` `Int` **optional** — Look for the last entries (paginate backward) ## Possible returns * `QueryFilterOrdersConnection` `QueryFilterOrdersConnection` - `edges` `[QueryFilterOrdersConnectionEdge]` **nullable** - `pageInfo` `PageInfo!` **non-null** # orderByExternalId (https://developer.godaddy.com/en/docs/references/rest/orders/order/queries/orderByExternalId) --- title: orderByExternalId description: Query `orderByExternalId` on the order subgraph (Order). full: true --- query Requires `commerce.order:read`. Query `orderByExternalId` on the order subgraph (Order). ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `externalId` `String!` **required** * `channelId` `String!` **required** ## Possible returns * `Order` `Order` - `billing` `BillingInfo` **nullable** — Order level billing snapshot information - `canceledAt` `DateTime` **nullable** — The datetime when the order was canceled - `cartId` `String` **nullable** — ID associated with a cart. Used to link orders and carts for Inventory tracking purposes - `completedAt` `DateTime` **nullable** — The datetime when the order was completed - `context` `Context` **nullable** — Context for an order - `createdAt` `DateTime` **nullable** — The datetime when the order was created in our system - `customerId` `String` **nullable** — Reference to a Customer as defined by the Connections service - `discounts` `[Discount!]` **nullable** — Discounts for an order - `externalId` `String` **nullable** — External identifier for the order. If provided, it must be a unique identifier at a channel level - `fees` `[Fee!]` **nullable** — Fees for an order - `fulfilledAt` `DateTime` **nullable** — The datetime when the order was completely fulfilled - `fulfillmentModes` `[String!]` **nullable** — Fulfillment modes for an order - `history` `[OrderHistoryType!]` **nullable** — History for an order - `id` `ID!` **non-null** — An identifier unique to the order node. Auto-generated by the service on the fly - `inventoryAction` `InventoryAction` **nullable** — Controls inventory adjustment behavior for this order - `lineItems` `[LineItem!]` **nullable** — Line items for an order - `links` `[Links!]` **nullable** — A request-related [HATEOAS link](https://datatracker.ietf.org/doc/html/draft-handrews-json-schema-hyperschema-02). - `metafields` `[OrderMetafield!]` **nullable** — Metafields that allow clients to specify more information about the order. Attributes present in this object will not map across all channels - `notes` `[Note!]` **nullable** — Notes for an order - `number` `String` **nullable** — An identifier unique to the order. The `number` field can be used to map an existing order to an order in the Order Service. Null until the order is assigned a number (for example, DRAFT orders). - `numberDisplay` `String` **nullable** — A human readable order number handed out to customers. Used for any communications with the customer (e.g. emails, SMS, or invoices). If not provided on creation, it will match the `number` attribute - `paidAt` `DateTime` **nullable** — The datetime when the order was completely paid - `processedAt` `DateTime` **nullable** — The datetime when the order was processed. If you are importing orders from an app or another platform, then you can set `processedAt` to a datetime in the past to match when the original order was created - `refundedAt` `DateTime` **nullable** — The datetime when the order was completely refunded - `returnTotals` `OrderReturnTotals` **nullable** — Grouped totals for an order return - `shipping` `ShippingInfo` **nullable** — Order level shipping snapshot information - `shippingLines` `[ShippingLine!]` **nullable** — Shipping lines for an order - `staffUserIds` `[String!]` **nullable** — Staff users associated with the Order - `statuses` `OrderStatuses` **nullable** — Current fulfillment status, payment status, and main status for the order - `tags` `[String!]` **nullable** — Comma delimited string of tags for an order. A tag should be an attribute of the order that does not change - `taxes` `[OrderTax!]` **nullable** — Taxes for an order - `taxExempted` `Boolean` **nullable** — Details whether the order is tax exempt - `totals` `OrderTotals` **nullable** — Grouped totals for an order - `transactionIds` `[String!]` **nullable** — Transactions as defined by the Transaction Service associated with the Order - `updatedAt` `DateTime` **nullable** — The datetime when the order was last updated in our system - `deprecatedNote` `String` **nullable** deprecated — Merchant note for an Order Deprecated: Replaced by the notes array # orderById (https://developer.godaddy.com/en/docs/references/rest/orders/order/queries/orderById) --- title: orderById description: Query `orderById` on the order subgraph (Order). full: true --- query Requires `commerce.order:read`. Query `orderById` on the order subgraph (Order). ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `ID!` **required** ## Possible returns * `Order` `Order` - `billing` `BillingInfo` **nullable** — Order level billing snapshot information - `canceledAt` `DateTime` **nullable** — The datetime when the order was canceled - `cartId` `String` **nullable** — ID associated with a cart. Used to link orders and carts for Inventory tracking purposes - `completedAt` `DateTime` **nullable** — The datetime when the order was completed - `context` `Context` **nullable** — Context for an order - `createdAt` `DateTime` **nullable** — The datetime when the order was created in our system - `customerId` `String` **nullable** — Reference to a Customer as defined by the Connections service - `discounts` `[Discount!]` **nullable** — Discounts for an order - `externalId` `String` **nullable** — External identifier for the order. If provided, it must be a unique identifier at a channel level - `fees` `[Fee!]` **nullable** — Fees for an order - `fulfilledAt` `DateTime` **nullable** — The datetime when the order was completely fulfilled - `fulfillmentModes` `[String!]` **nullable** — Fulfillment modes for an order - `history` `[OrderHistoryType!]` **nullable** — History for an order - `id` `ID!` **non-null** — An identifier unique to the order node. Auto-generated by the service on the fly - `inventoryAction` `InventoryAction` **nullable** — Controls inventory adjustment behavior for this order - `lineItems` `[LineItem!]` **nullable** — Line items for an order - `links` `[Links!]` **nullable** — A request-related [HATEOAS link](https://datatracker.ietf.org/doc/html/draft-handrews-json-schema-hyperschema-02). - `metafields` `[OrderMetafield!]` **nullable** — Metafields that allow clients to specify more information about the order. Attributes present in this object will not map across all channels - `notes` `[Note!]` **nullable** — Notes for an order - `number` `String` **nullable** — An identifier unique to the order. The `number` field can be used to map an existing order to an order in the Order Service. Null until the order is assigned a number (for example, DRAFT orders). - `numberDisplay` `String` **nullable** — A human readable order number handed out to customers. Used for any communications with the customer (e.g. emails, SMS, or invoices). If not provided on creation, it will match the `number` attribute - `paidAt` `DateTime` **nullable** — The datetime when the order was completely paid - `processedAt` `DateTime` **nullable** — The datetime when the order was processed. If you are importing orders from an app or another platform, then you can set `processedAt` to a datetime in the past to match when the original order was created - `refundedAt` `DateTime` **nullable** — The datetime when the order was completely refunded - `returnTotals` `OrderReturnTotals` **nullable** — Grouped totals for an order return - `shipping` `ShippingInfo` **nullable** — Order level shipping snapshot information - `shippingLines` `[ShippingLine!]` **nullable** — Shipping lines for an order - `staffUserIds` `[String!]` **nullable** — Staff users associated with the Order - `statuses` `OrderStatuses` **nullable** — Current fulfillment status, payment status, and main status for the order - `tags` `[String!]` **nullable** — Comma delimited string of tags for an order. A tag should be an attribute of the order that does not change - `taxes` `[OrderTax!]` **nullable** — Taxes for an order - `taxExempted` `Boolean` **nullable** — Details whether the order is tax exempt - `totals` `OrderTotals` **nullable** — Grouped totals for an order - `transactionIds` `[String!]` **nullable** — Transactions as defined by the Transaction Service associated with the Order - `updatedAt` `DateTime` **nullable** — The datetime when the order was last updated in our system - `deprecatedNote` `String` **nullable** deprecated — Merchant note for an Order Deprecated: Replaced by the notes array # orderByNumber (https://developer.godaddy.com/en/docs/references/rest/orders/order/queries/orderByNumber) --- title: orderByNumber description: Query `orderByNumber` on the order subgraph (Order). full: true --- query Requires `commerce.order:read`. Query `orderByNumber` on the order subgraph (Order). ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `number` `String!` **required** ## Possible returns * `Order` `Order` - `billing` `BillingInfo` **nullable** — Order level billing snapshot information - `canceledAt` `DateTime` **nullable** — The datetime when the order was canceled - `cartId` `String` **nullable** — ID associated with a cart. Used to link orders and carts for Inventory tracking purposes - `completedAt` `DateTime` **nullable** — The datetime when the order was completed - `context` `Context` **nullable** — Context for an order - `createdAt` `DateTime` **nullable** — The datetime when the order was created in our system - `customerId` `String` **nullable** — Reference to a Customer as defined by the Connections service - `discounts` `[Discount!]` **nullable** — Discounts for an order - `externalId` `String` **nullable** — External identifier for the order. If provided, it must be a unique identifier at a channel level - `fees` `[Fee!]` **nullable** — Fees for an order - `fulfilledAt` `DateTime` **nullable** — The datetime when the order was completely fulfilled - `fulfillmentModes` `[String!]` **nullable** — Fulfillment modes for an order - `history` `[OrderHistoryType!]` **nullable** — History for an order - `id` `ID!` **non-null** — An identifier unique to the order node. Auto-generated by the service on the fly - `inventoryAction` `InventoryAction` **nullable** — Controls inventory adjustment behavior for this order - `lineItems` `[LineItem!]` **nullable** — Line items for an order - `links` `[Links!]` **nullable** — A request-related [HATEOAS link](https://datatracker.ietf.org/doc/html/draft-handrews-json-schema-hyperschema-02). - `metafields` `[OrderMetafield!]` **nullable** — Metafields that allow clients to specify more information about the order. Attributes present in this object will not map across all channels - `notes` `[Note!]` **nullable** — Notes for an order - `number` `String` **nullable** — An identifier unique to the order. The `number` field can be used to map an existing order to an order in the Order Service. Null until the order is assigned a number (for example, DRAFT orders). - `numberDisplay` `String` **nullable** — A human readable order number handed out to customers. Used for any communications with the customer (e.g. emails, SMS, or invoices). If not provided on creation, it will match the `number` attribute - `paidAt` `DateTime` **nullable** — The datetime when the order was completely paid - `processedAt` `DateTime` **nullable** — The datetime when the order was processed. If you are importing orders from an app or another platform, then you can set `processedAt` to a datetime in the past to match when the original order was created - `refundedAt` `DateTime` **nullable** — The datetime when the order was completely refunded - `returnTotals` `OrderReturnTotals` **nullable** — Grouped totals for an order return - `shipping` `ShippingInfo` **nullable** — Order level shipping snapshot information - `shippingLines` `[ShippingLine!]` **nullable** — Shipping lines for an order - `staffUserIds` `[String!]` **nullable** — Staff users associated with the Order - `statuses` `OrderStatuses` **nullable** — Current fulfillment status, payment status, and main status for the order - `tags` `[String!]` **nullable** — Comma delimited string of tags for an order. A tag should be an attribute of the order that does not change - `taxes` `[OrderTax!]` **nullable** — Taxes for an order - `taxExempted` `Boolean` **nullable** — Details whether the order is tax exempt - `totals` `OrderTotals` **nullable** — Grouped totals for an order - `transactionIds` `[String!]` **nullable** — Transactions as defined by the Transaction Service associated with the Order - `updatedAt` `DateTime` **nullable** — The datetime when the order was last updated in our system - `deprecatedNote` `String` **nullable** deprecated — Merchant note for an Order Deprecated: Replaced by the notes array # orders (https://developer.godaddy.com/en/docs/references/rest/orders/order/queries/orders) --- title: orders description: Query `orders` on the order subgraph (Order). full: true --- query Requires `commerce.order:read`. Query `orders` on the order subgraph (Order). ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `before` `ID` **optional** — Look for entries before that cursor * `after` `ID` **optional** — Look for entries after that cursor * `first` `Int` **optional** — Look for the first entries (paginate forward) * `last` `Int` **optional** — Look for the last entries (paginate backward) ## Possible returns * `QueryOrdersConnection` `QueryOrdersConnection` - `edges` `[QueryOrdersConnectionEdge]` **nullable** - `pageInfo` `PageInfo!` **non-null** # ordersByIds (https://developer.godaddy.com/en/docs/references/rest/orders/order/queries/ordersByIds) --- title: ordersByIds description: Query `ordersByIds` on the order subgraph (Order). full: true --- query Requires `commerce.order:read`. Query `ordersByIds` on the order subgraph (Order). ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `ids` `[ID!]!` **required** ## Possible returns * `Order` `[Order!]` - `billing` `BillingInfo` **nullable** — Order level billing snapshot information - `canceledAt` `DateTime` **nullable** — The datetime when the order was canceled - `cartId` `String` **nullable** — ID associated with a cart. Used to link orders and carts for Inventory tracking purposes - `completedAt` `DateTime` **nullable** — The datetime when the order was completed - `context` `Context` **nullable** — Context for an order - `createdAt` `DateTime` **nullable** — The datetime when the order was created in our system - `customerId` `String` **nullable** — Reference to a Customer as defined by the Connections service - `discounts` `[Discount!]` **nullable** — Discounts for an order - `externalId` `String` **nullable** — External identifier for the order. If provided, it must be a unique identifier at a channel level - `fees` `[Fee!]` **nullable** — Fees for an order - `fulfilledAt` `DateTime` **nullable** — The datetime when the order was completely fulfilled - `fulfillmentModes` `[String!]` **nullable** — Fulfillment modes for an order - `history` `[OrderHistoryType!]` **nullable** — History for an order - `id` `ID!` **non-null** — An identifier unique to the order node. Auto-generated by the service on the fly - `inventoryAction` `InventoryAction` **nullable** — Controls inventory adjustment behavior for this order - `lineItems` `[LineItem!]` **nullable** — Line items for an order - `links` `[Links!]` **nullable** — A request-related [HATEOAS link](https://datatracker.ietf.org/doc/html/draft-handrews-json-schema-hyperschema-02). - `metafields` `[OrderMetafield!]` **nullable** — Metafields that allow clients to specify more information about the order. Attributes present in this object will not map across all channels - `notes` `[Note!]` **nullable** — Notes for an order - `number` `String` **nullable** — An identifier unique to the order. The `number` field can be used to map an existing order to an order in the Order Service. Null until the order is assigned a number (for example, DRAFT orders). - `numberDisplay` `String` **nullable** — A human readable order number handed out to customers. Used for any communications with the customer (e.g. emails, SMS, or invoices). If not provided on creation, it will match the `number` attribute - `paidAt` `DateTime` **nullable** — The datetime when the order was completely paid - `processedAt` `DateTime` **nullable** — The datetime when the order was processed. If you are importing orders from an app or another platform, then you can set `processedAt` to a datetime in the past to match when the original order was created - `refundedAt` `DateTime` **nullable** — The datetime when the order was completely refunded - `returnTotals` `OrderReturnTotals` **nullable** — Grouped totals for an order return - `shipping` `ShippingInfo` **nullable** — Order level shipping snapshot information - `shippingLines` `[ShippingLine!]` **nullable** — Shipping lines for an order - `staffUserIds` `[String!]` **nullable** — Staff users associated with the Order - `statuses` `OrderStatuses` **nullable** — Current fulfillment status, payment status, and main status for the order - `tags` `[String!]` **nullable** — Comma delimited string of tags for an order. A tag should be an attribute of the order that does not change - `taxes` `[OrderTax!]` **nullable** — Taxes for an order - `taxExempted` `Boolean` **nullable** — Details whether the order is tax exempt - `totals` `OrderTotals` **nullable** — Grouped totals for an order - `transactionIds` `[String!]` **nullable** — Transactions as defined by the Transaction Service associated with the Order - `updatedAt` `DateTime` **nullable** — The datetime when the order was last updated in our system - `deprecatedNote` `String` **nullable** deprecated — Merchant note for an Order Deprecated: Replaced by the notes array # addListsToClassification (https://developer.godaddy.com/en/docs/references/rest/taxes/classification/mutations/addListsToClassification) --- title: addListsToClassification description: Add existing lists to an existing classification. full: true --- mutation Requires `commerce.tax:write`. Add existing lists to an existing classification. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `classificationId` `ID!` **required** — The ID of the classification to which the lists should be added. * `input` `MutationAddListsToClassificationInput!` **required** * `listIds` `[ID!]!` **required** — The IDs of the lists to be added to the classification. ## Possible returns * `Classification` `Classification` — A grouping of rates that share common taxation criteria. - `createdAt` `DateTime!` **non-null** — The data & time at which the classification was created. - `description` `String` **nullable** — The human-friendly description. - `id` `ID!` **non-null** — The globally-unique ID. - `label` `String!` **non-null** — The label for display. - `lists` `ClassificationListsConnection` **nullable** — The catalog lists to which the classification applies. - `metafields` `ClassificationMetafieldsConnection` **nullable** - `name` `String!` **non-null** — The unique human-friendly identifier. - `rates` `ClassificationRatesConnection` **nullable** — The rates associated with the classification. - `references` `ClassificationReferencesConnection` **nullable** — A reference to the resource in an external service. - `skuGroups` `ClassificationSkuGroupsConnection` **nullable** — The catalog SKU groups to which the classification applies. - `skus` `ClassificationSkusConnection` **nullable** — The catalog SKUs to which the classification applies. - `updatedAt` `DateTime!` **non-null** — The data & time at which the classification was last updated. # addRatesToClassification (https://developer.godaddy.com/en/docs/references/rest/taxes/classification/mutations/addRatesToClassification) --- title: addRatesToClassification description: Add existing rates to an existing classification. full: true --- mutation Requires `commerce.tax:write`. Add existing rates to an existing classification. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `classificationId` `ID!` **required** — The ID of the classification to which the rates should be added. * `input` `MutationAddRatesToClassificationInput!` **required** * `rateIds` `[ID!]!` **required** — The IDs of the rates to be added to the classification. ## Possible returns * `Classification` `Classification` — A grouping of rates that share common taxation criteria. - `createdAt` `DateTime!` **non-null** — The data & time at which the classification was created. - `description` `String` **nullable** — The human-friendly description. - `id` `ID!` **non-null** — The globally-unique ID. - `label` `String!` **non-null** — The label for display. - `lists` `ClassificationListsConnection` **nullable** — The catalog lists to which the classification applies. - `metafields` `ClassificationMetafieldsConnection` **nullable** - `name` `String!` **non-null** — The unique human-friendly identifier. - `rates` `ClassificationRatesConnection` **nullable** — The rates associated with the classification. - `references` `ClassificationReferencesConnection` **nullable** — A reference to the resource in an external service. - `skuGroups` `ClassificationSkuGroupsConnection` **nullable** — The catalog SKU groups to which the classification applies. - `skus` `ClassificationSkusConnection` **nullable** — The catalog SKUs to which the classification applies. - `updatedAt` `DateTime!` **non-null** — The data & time at which the classification was last updated. # addSkusGroupsToClassification (https://developer.godaddy.com/en/docs/references/rest/taxes/classification/mutations/addSkusGroupsToClassification) --- title: addSkusGroupsToClassification description: Add existing SKU groups to an existing classification. full: true --- mutation Requires `commerce.tax:write`. Add existing SKU groups to an existing classification. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `classificationId` `ID!` **required** — The ID of the classification to which the SKU groups should be added. * `input` `MutationAddSkusGroupsToClassificationInput!` **required** * `skuGroupIds` `[ID!]!` **required** — The IDs of the SKU groups to be added to the classification. ## Possible returns * `Classification` `Classification` — A grouping of rates that share common taxation criteria. - `createdAt` `DateTime!` **non-null** — The data & time at which the classification was created. - `description` `String` **nullable** — The human-friendly description. - `id` `ID!` **non-null** — The globally-unique ID. - `label` `String!` **non-null** — The label for display. - `lists` `ClassificationListsConnection` **nullable** — The catalog lists to which the classification applies. - `metafields` `ClassificationMetafieldsConnection` **nullable** - `name` `String!` **non-null** — The unique human-friendly identifier. - `rates` `ClassificationRatesConnection` **nullable** — The rates associated with the classification. - `references` `ClassificationReferencesConnection` **nullable** — A reference to the resource in an external service. - `skuGroups` `ClassificationSkuGroupsConnection` **nullable** — The catalog SKU groups to which the classification applies. - `skus` `ClassificationSkusConnection` **nullable** — The catalog SKUs to which the classification applies. - `updatedAt` `DateTime!` **non-null** — The data & time at which the classification was last updated. # addSkusToClassification (https://developer.godaddy.com/en/docs/references/rest/taxes/classification/mutations/addSkusToClassification) --- title: addSkusToClassification description: Add existing SKUs to an existing classification. full: true --- mutation Requires `commerce.tax:write`. Add existing SKUs to an existing classification. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `classificationId` `ID!` **required** — The ID of the classification to which the SKUs should be added. * `input` `MutationAddSkusToClassificationInput!` **required** * `skuIds` `[ID!]!` **required** — The IDs of the SKUs to be added to the classification. ## Possible returns * `Classification` `Classification` — A grouping of rates that share common taxation criteria. - `createdAt` `DateTime!` **non-null** — The data & time at which the classification was created. - `description` `String` **nullable** — The human-friendly description. - `id` `ID!` **non-null** — The globally-unique ID. - `label` `String!` **non-null** — The label for display. - `lists` `ClassificationListsConnection` **nullable** — The catalog lists to which the classification applies. - `metafields` `ClassificationMetafieldsConnection` **nullable** - `name` `String!` **non-null** — The unique human-friendly identifier. - `rates` `ClassificationRatesConnection` **nullable** — The rates associated with the classification. - `references` `ClassificationReferencesConnection` **nullable** — A reference to the resource in an external service. - `skuGroups` `ClassificationSkuGroupsConnection` **nullable** — The catalog SKU groups to which the classification applies. - `skus` `ClassificationSkusConnection` **nullable** — The catalog SKUs to which the classification applies. - `updatedAt` `DateTime!` **non-null** — The data & time at which the classification was last updated. # createClassification (https://developer.godaddy.com/en/docs/references/rest/taxes/classification/mutations/createClassification) --- title: createClassification description: Create a new classification. full: true --- mutation Requires `commerce.tax:create`. Create a new classification. `metafields` and `references` are optional — omit them. If you send `metafields`, the array must be nonempty; `[]` is rejected. Prefer `type: "string"` (lowercase). ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `input` `MutationCreateClassificationInput!` **required** * `label` `String!` **required** — A label for display. * `description` `String` **optional** — A human-friendly description. * `metafields` `[CreateMetafieldInput!]` **optional** — Any metafields to be created and assigned to the new classification. * `key` `String!` **required** * `namespace` `String!` **required** * `type` `String!` **required** — Metafield value type. Live catalog validation accepts lowercase values such as `boolean`, `string`, `stringMultiLine`, `number`, `numberDecimal`, `date`, `dateTime`, `json`, `measurement`, `url`, `reference`, `money`, `list.string`, `list.number`, `list.numberDecimal`. Uppercase `STRING` is rejected. * `value` `String!` **required** * `name` `String` **optional** — A unique human-friendly identifier. If omitted, a name will be generated from the `label` value. * `references` `[CreateReferenceInput!]` **optional** — Any references to be created and assigned to the new classification. * `origin` `String!` **required** — The origin of the reference. * `value` `String!` **required** — The value of the reference. ## Possible returns * `Classification` `Classification` — A grouping of rates that share common taxation criteria. - `createdAt` `DateTime!` **non-null** — The data & time at which the classification was created. - `description` `String` **nullable** — The human-friendly description. - `id` `ID!` **non-null** — The globally-unique ID. - `label` `String!` **non-null** — The label for display. - `lists` `ClassificationListsConnection` **nullable** — The catalog lists to which the classification applies. - `metafields` `ClassificationMetafieldsConnection` **nullable** - `name` `String!` **non-null** — The unique human-friendly identifier. - `rates` `ClassificationRatesConnection` **nullable** — The rates associated with the classification. - `references` `ClassificationReferencesConnection` **nullable** — A reference to the resource in an external service. - `skuGroups` `ClassificationSkuGroupsConnection` **nullable** — The catalog SKU groups to which the classification applies. - `skus` `ClassificationSkusConnection` **nullable** — The catalog SKUs to which the classification applies. - `updatedAt` `DateTime!` **non-null** — The data & time at which the classification was last updated. # createReferencesForClassification (https://developer.godaddy.com/en/docs/references/rest/taxes/classification/mutations/createReferencesForClassification) --- title: createReferencesForClassification description: Create references for an existing classification. full: true --- mutation Requires `commerce.tax:create`. Create references for an existing classification. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `ID!` **required** — The ID of the classification for which the references should be created. * `input` `MutationCreateReferencesForClassificationInput!` **required** * `references` `[CreateReferenceInput!]!` **required** — The references to be created for the classification. * `origin` `String!` **required** — The origin of the reference. * `value` `String!` **required** — The value of the reference. ## Possible returns * `Classification` `Classification` — A grouping of rates that share common taxation criteria. - `createdAt` `DateTime!` **non-null** — The data & time at which the classification was created. - `description` `String` **nullable** — The human-friendly description. - `id` `ID!` **non-null** — The globally-unique ID. - `label` `String!` **non-null** — The label for display. - `lists` `ClassificationListsConnection` **nullable** — The catalog lists to which the classification applies. - `metafields` `ClassificationMetafieldsConnection` **nullable** - `name` `String!` **non-null** — The unique human-friendly identifier. - `rates` `ClassificationRatesConnection` **nullable** — The rates associated with the classification. - `references` `ClassificationReferencesConnection` **nullable** — A reference to the resource in an external service. - `skuGroups` `ClassificationSkuGroupsConnection` **nullable** — The catalog SKU groups to which the classification applies. - `skus` `ClassificationSkusConnection` **nullable** — The catalog SKUs to which the classification applies. - `updatedAt` `DateTime!` **non-null** — The data & time at which the classification was last updated. # deleteClassification (https://developer.godaddy.com/en/docs/references/rest/taxes/classification/mutations/deleteClassification) --- title: deleteClassification description: Delete an existing classification. full: true --- mutation Requires `commerce.tax:delete`. Delete an existing classification. Returns the deleted `Classification`. Selecting no subfields is a GraphQL validation error. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `ID!` **required** — The ID of the classification to be deleted. ## Possible returns * `Classification` `Classification` — A grouping of rates that share common taxation criteria. - `createdAt` `DateTime!` **non-null** — The data & time at which the classification was created. - `description` `String` **nullable** — The human-friendly description. - `id` `ID!` **non-null** — The globally-unique ID. - `label` `String!` **non-null** — The label for display. - `lists` `ClassificationListsConnection` **nullable** — The catalog lists to which the classification applies. - `metafields` `ClassificationMetafieldsConnection` **nullable** - `name` `String!` **non-null** — The unique human-friendly identifier. - `rates` `ClassificationRatesConnection` **nullable** — The rates associated with the classification. - `references` `ClassificationReferencesConnection` **nullable** — A reference to the resource in an external service. - `skuGroups` `ClassificationSkuGroupsConnection` **nullable** — The catalog SKU groups to which the classification applies. - `skus` `ClassificationSkusConnection` **nullable** — The catalog SKUs to which the classification applies. - `updatedAt` `DateTime!` **non-null** — The data & time at which the classification was last updated. # deleteReferencesFromClassification (https://developer.godaddy.com/en/docs/references/rest/taxes/classification/mutations/deleteReferencesFromClassification) --- title: deleteReferencesFromClassification description: Delete references from an existing classification. full: true --- mutation Requires `commerce.tax:delete`. Delete references from an existing classification. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `ID!` **required** — The ID of the classification for which the references should be deleted. * `input` `MutationDeleteReferencesFromClassificationInput!` **required** * `referenceIds` `[ID!]!` **required** — The IDs of the references to be deleted from the classification. ## Possible returns * `Classification` `Classification` — A grouping of rates that share common taxation criteria. - `createdAt` `DateTime!` **non-null** — The data & time at which the classification was created. - `description` `String` **nullable** — The human-friendly description. - `id` `ID!` **non-null** — The globally-unique ID. - `label` `String!` **non-null** — The label for display. - `lists` `ClassificationListsConnection` **nullable** — The catalog lists to which the classification applies. - `metafields` `ClassificationMetafieldsConnection` **nullable** - `name` `String!` **non-null** — The unique human-friendly identifier. - `rates` `ClassificationRatesConnection` **nullable** — The rates associated with the classification. - `references` `ClassificationReferencesConnection` **nullable** — A reference to the resource in an external service. - `skuGroups` `ClassificationSkuGroupsConnection` **nullable** — The catalog SKU groups to which the classification applies. - `skus` `ClassificationSkusConnection` **nullable** — The catalog SKUs to which the classification applies. - `updatedAt` `DateTime!` **non-null** — The data & time at which the classification was last updated. # removeListsFromClassification (https://developer.godaddy.com/en/docs/references/rest/taxes/classification/mutations/removeListsFromClassification) --- title: removeListsFromClassification description: Remove existing lists from an existing classification. full: true --- mutation Requires `commerce.tax:write`. Remove existing lists from an existing classification. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `classificationId` `ID!` **required** — The ID of the classification to which the lists should be removed. * `input` `MutationRemoveListsFromClassificationInput!` **required** * `listIds` `[ID!]!` **required** — The IDs of the lists to be removed from the classification. ## Possible returns * `Classification` `Classification` — A grouping of rates that share common taxation criteria. - `createdAt` `DateTime!` **non-null** — The data & time at which the classification was created. - `description` `String` **nullable** — The human-friendly description. - `id` `ID!` **non-null** — The globally-unique ID. - `label` `String!` **non-null** — The label for display. - `lists` `ClassificationListsConnection` **nullable** — The catalog lists to which the classification applies. - `metafields` `ClassificationMetafieldsConnection` **nullable** - `name` `String!` **non-null** — The unique human-friendly identifier. - `rates` `ClassificationRatesConnection` **nullable** — The rates associated with the classification. - `references` `ClassificationReferencesConnection` **nullable** — A reference to the resource in an external service. - `skuGroups` `ClassificationSkuGroupsConnection` **nullable** — The catalog SKU groups to which the classification applies. - `skus` `ClassificationSkusConnection` **nullable** — The catalog SKUs to which the classification applies. - `updatedAt` `DateTime!` **non-null** — The data & time at which the classification was last updated. # removeRatesFromClassification (https://developer.godaddy.com/en/docs/references/rest/taxes/classification/mutations/removeRatesFromClassification) --- title: removeRatesFromClassification description: Remove existing rates from an existing classification. full: true --- mutation Requires `commerce.tax:write`. Remove existing rates from an existing classification. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `classificationId` `ID!` **required** — The ID of the classification to which the rates should be removed. * `input` `MutationRemoveRatesFromClassificationInput!` **required** * `rateIds` `[ID!]!` **required** — The IDs of the rates to be removed from the classification. ## Possible returns * `Classification` `Classification` — A grouping of rates that share common taxation criteria. - `createdAt` `DateTime!` **non-null** — The data & time at which the classification was created. - `description` `String` **nullable** — The human-friendly description. - `id` `ID!` **non-null** — The globally-unique ID. - `label` `String!` **non-null** — The label for display. - `lists` `ClassificationListsConnection` **nullable** — The catalog lists to which the classification applies. - `metafields` `ClassificationMetafieldsConnection` **nullable** - `name` `String!` **non-null** — The unique human-friendly identifier. - `rates` `ClassificationRatesConnection` **nullable** — The rates associated with the classification. - `references` `ClassificationReferencesConnection` **nullable** — A reference to the resource in an external service. - `skuGroups` `ClassificationSkuGroupsConnection` **nullable** — The catalog SKU groups to which the classification applies. - `skus` `ClassificationSkusConnection` **nullable** — The catalog SKUs to which the classification applies. - `updatedAt` `DateTime!` **non-null** — The data & time at which the classification was last updated. # removeSkusFromClassification (https://developer.godaddy.com/en/docs/references/rest/taxes/classification/mutations/removeSkusFromClassification) --- title: removeSkusFromClassification description: Remove existing SKUs from an existing classification. full: true --- mutation Requires `commerce.tax:write`. Remove existing SKUs from an existing classification. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `classificationId` `ID!` **required** — The ID of the classification to which the SKUs should be removed. * `input` `MutationRemoveSkusFromClassificationInput!` **required** * `skuIds` `[ID!]!` **required** — The IDs of the SKUs to be removed from the classification. ## Possible returns * `Classification` `Classification` — A grouping of rates that share common taxation criteria. - `createdAt` `DateTime!` **non-null** — The data & time at which the classification was created. - `description` `String` **nullable** — The human-friendly description. - `id` `ID!` **non-null** — The globally-unique ID. - `label` `String!` **non-null** — The label for display. - `lists` `ClassificationListsConnection` **nullable** — The catalog lists to which the classification applies. - `metafields` `ClassificationMetafieldsConnection` **nullable** - `name` `String!` **non-null** — The unique human-friendly identifier. - `rates` `ClassificationRatesConnection` **nullable** — The rates associated with the classification. - `references` `ClassificationReferencesConnection` **nullable** — A reference to the resource in an external service. - `skuGroups` `ClassificationSkuGroupsConnection` **nullable** — The catalog SKU groups to which the classification applies. - `skus` `ClassificationSkusConnection` **nullable** — The catalog SKUs to which the classification applies. - `updatedAt` `DateTime!` **non-null** — The data & time at which the classification was last updated. # removeSkusGroupsFromClassification (https://developer.godaddy.com/en/docs/references/rest/taxes/classification/mutations/removeSkusGroupsFromClassification) --- title: removeSkusGroupsFromClassification description: Remove existing SKU groups from an existing classification. full: true --- mutation Requires `commerce.tax:write`. Remove existing SKU groups from an existing classification. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `classificationId` `ID!` **required** — The ID of the classification to which the SKU groups should be added. * `input` `MutationRemoveSkusGroupsFromClassificationInput!` **required** * `skuGroupIds` `[ID!]!` **required** — The IDs of the SKU groups to be removed from the classification. ## Possible returns * `Classification` `Classification` — A grouping of rates that share common taxation criteria. - `createdAt` `DateTime!` **non-null** — The data & time at which the classification was created. - `description` `String` **nullable** — The human-friendly description. - `id` `ID!` **non-null** — The globally-unique ID. - `label` `String!` **non-null** — The label for display. - `lists` `ClassificationListsConnection` **nullable** — The catalog lists to which the classification applies. - `metafields` `ClassificationMetafieldsConnection` **nullable** - `name` `String!` **non-null** — The unique human-friendly identifier. - `rates` `ClassificationRatesConnection` **nullable** — The rates associated with the classification. - `references` `ClassificationReferencesConnection` **nullable** — A reference to the resource in an external service. - `skuGroups` `ClassificationSkuGroupsConnection` **nullable** — The catalog SKU groups to which the classification applies. - `skus` `ClassificationSkusConnection` **nullable** — The catalog SKUs to which the classification applies. - `updatedAt` `DateTime!` **non-null** — The data & time at which the classification was last updated. # updateClassification (https://developer.godaddy.com/en/docs/references/rest/taxes/classification/mutations/updateClassification) --- title: updateClassification description: Update an existing classification. full: true --- mutation Requires `commerce.tax:write`. Update an existing classification. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `ID!` **required** — The ID of the classification to be updated. * `input` `MutationUpdateClassificationInput!` **required** * `description` `String` **optional** — A human-friendly description. * `label` `String` **optional** — A label for display. * `name` `String` **optional** — A unique human-friendly identifier. ## Possible returns * `Classification` `Classification` — A grouping of rates that share common taxation criteria. - `createdAt` `DateTime!` **non-null** — The data & time at which the classification was created. - `description` `String` **nullable** — The human-friendly description. - `id` `ID!` **non-null** — The globally-unique ID. - `label` `String!` **non-null** — The label for display. - `lists` `ClassificationListsConnection` **nullable** — The catalog lists to which the classification applies. - `metafields` `ClassificationMetafieldsConnection` **nullable** - `name` `String!` **non-null** — The unique human-friendly identifier. - `rates` `ClassificationRatesConnection` **nullable** — The rates associated with the classification. - `references` `ClassificationReferencesConnection` **nullable** — A reference to the resource in an external service. - `skuGroups` `ClassificationSkuGroupsConnection` **nullable** — The catalog SKU groups to which the classification applies. - `skus` `ClassificationSkusConnection` **nullable** — The catalog SKUs to which the classification applies. - `updatedAt` `DateTime!` **non-null** — The data & time at which the classification was last updated. # classification (https://developer.godaddy.com/en/docs/references/rest/taxes/classification/queries/classification) --- title: classification description: Get a single classification. full: true --- query Requires `commerce.tax:read`. Get a single classification. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `ID!` **required** — The classification ID. ## Possible returns * `Classification` `Classification` — A grouping of rates that share common taxation criteria. - `createdAt` `DateTime!` **non-null** — The data & time at which the classification was created. - `description` `String` **nullable** — The human-friendly description. - `id` `ID!` **non-null** — The globally-unique ID. - `label` `String!` **non-null** — The label for display. - `lists` `ClassificationListsConnection` **nullable** — The catalog lists to which the classification applies. - `metafields` `ClassificationMetafieldsConnection` **nullable** - `name` `String!` **non-null** — The unique human-friendly identifier. - `rates` `ClassificationRatesConnection` **nullable** — The rates associated with the classification. - `references` `ClassificationReferencesConnection` **nullable** — A reference to the resource in an external service. - `skuGroups` `ClassificationSkuGroupsConnection` **nullable** — The catalog SKU groups to which the classification applies. - `skus` `ClassificationSkusConnection` **nullable** — The catalog SKUs to which the classification applies. - `updatedAt` `DateTime!` **non-null** — The data & time at which the classification was last updated. # classifications (https://developer.godaddy.com/en/docs/references/rest/taxes/classification/queries/classifications) --- title: classifications description: Get a collection of classifications. full: true --- query Requires `commerce.tax:read`. Get a collection of classifications. `orderBy` is one key only (`id`, `name`, `createdAt`, or `updatedAt`). Direction must be `ASC` or `DESC`. Sending two keys, or `"desc"`, fails validation. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `after` `String` **optional** * `before` `String` **optional** * `first` `Int` **optional** * `id` `ClassificationIdFilter` **optional** * `in` `[ID!]` **optional** * `last` `Int` **optional** * `orderBy` `ClassificationOrderBy` **optional** * `createdAt` `OrderByDirectionEnum` **optional** * `id` `OrderByDirectionEnum` **optional** * `name` `OrderByDirectionEnum` **optional** * `updatedAt` `OrderByDirectionEnum` **optional** ## Possible returns * `QueryClassificationsConnection` `QueryClassificationsConnection` - `edges` `[QueryClassificationsConnectionEdge]` **nullable** - `pageInfo` `PageInfo!` **non-null** # createJurisdiction (https://developer.godaddy.com/en/docs/references/rest/taxes/jurisdiction/mutations/createJurisdiction) --- title: createJurisdiction description: Create a new jurisdiction. full: true --- mutation Requires `commerce.tax:create`. Create a new jurisdiction. `metafields` is optional — omit it. If you send it, the array must be nonempty; `[]` is rejected. Prefer `type: "string"` (lowercase). ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `input` `MutationCreateJurisdictionInput!` **required** * `countryCode` `String!` **required** — The [two-character ISO 3166-1 code](https://en.wikipedia.org/wiki/ISO_3166-1) that identifies the country or region. * `adminArea1` `String` **optional** — The highest level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision; formatted for postal delivery. * `adminArea2` `String` **optional** — The city, town, or village. Smaller than `adminArea1`. * `adminArea3` `String` **optional** — The sub-locality, suburb, neighborhood, or district. Smaller than `adminArea2`. * `adminArea4` `String` **optional** — The neighborhood, ward, or district. Smaller than `adminArea3`. * `metafields` `[CreateMetafieldInput!]` **optional** — Any metafields to be created and assigned to the new jurisdiction. * `key` `String!` **required** * `namespace` `String!` **required** * `type` `String!` **required** — Metafield value type. Live catalog validation accepts lowercase values such as `boolean`, `string`, `stringMultiLine`, `number`, `numberDecimal`, `date`, `dateTime`, `json`, `measurement`, `url`, `reference`, `money`, `list.string`, `list.number`, `list.numberDecimal`. Uppercase `STRING` is rejected. * `value` `String!` **required** * `postalCode` `String` **optional** — The postal code, which is the zip code or equivalent. ## Possible returns * `Jurisdiction` `Jurisdiction` — A geographic area or "zone" in which a rate or set of rates applies. - `adminArea1` `String` **nullable** — The highest level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. - `adminArea2` `String` **nullable** — The city, town, or village. - `adminArea3` `String` **nullable** — The sub-locality, suburb, neighborhood, or district. - `adminArea4` `String` **nullable** — The neighborhood, ward, or district. - `countryCode` `String!` **non-null** — The country code of the address. - `createdAt` `DateTime!` **non-null** — The data & time at which the jurisdiction was created. - `id` `ID!` **non-null** — The globally-unique ID. - `metafields` `JurisdictionMetafieldsConnection` **nullable** - `postalCode` `String` **nullable** — The postal code of the address. - `rates` `JurisdictionRatesConnection` **nullable** — The rates associated with the jurisdiction. - `updatedAt` `DateTime!` **non-null** — The data & time at which the jurisdiction was last updated. # deleteJurisdiction (https://developer.godaddy.com/en/docs/references/rest/taxes/jurisdiction/mutations/deleteJurisdiction) --- title: deleteJurisdiction description: Delete an existing jurisdiction. full: true --- mutation Requires `commerce.tax:delete`. Delete an existing jurisdiction. Returns the deleted `Jurisdiction`. Selecting no subfields is a GraphQL validation error. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `ID!` **required** — The ID of the jurisdiction to be deleted. ## Possible returns * `Jurisdiction` `Jurisdiction` — A geographic area or "zone" in which a rate or set of rates applies. - `adminArea1` `String` **nullable** — The highest level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. - `adminArea2` `String` **nullable** — The city, town, or village. - `adminArea3` `String` **nullable** — The sub-locality, suburb, neighborhood, or district. - `adminArea4` `String` **nullable** — The neighborhood, ward, or district. - `countryCode` `String!` **non-null** — The country code of the address. - `createdAt` `DateTime!` **non-null** — The data & time at which the jurisdiction was created. - `id` `ID!` **non-null** — The globally-unique ID. - `metafields` `JurisdictionMetafieldsConnection` **nullable** - `postalCode` `String` **nullable** — The postal code of the address. - `rates` `JurisdictionRatesConnection` **nullable** — The rates associated with the jurisdiction. - `updatedAt` `DateTime!` **non-null** — The data & time at which the jurisdiction was last updated. # updateJurisdiction (https://developer.godaddy.com/en/docs/references/rest/taxes/jurisdiction/mutations/updateJurisdiction) --- title: updateJurisdiction description: Update an existing jurisdiction. full: true --- mutation Requires `commerce.tax:write`. Update an existing jurisdiction. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `ID!` **required** — The ID of the jurisdiction to be updated. * `input` `MutationUpdateJurisdictionInput!` **required** * `adminArea1` `String` **optional** — The highest level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision; formatted for postal delivery. * `adminArea2` `String` **optional** — The city, town, or village. Smaller than `adminArea1`. * `adminArea3` `String` **optional** — The sub-locality, suburb, neighborhood, or district. Smaller than `adminArea2`. * `adminArea4` `String` **optional** — The neighborhood, ward, or district. Smaller than `adminArea3`. * `countryCode` `String` **optional** — The [two-character ISO 3166-1 code](https://en.wikipedia.org/wiki/ISO_3166-1) that identifies the country or region. * `postalCode` `String` **optional** — The postal code, which is the zip code or equivalent. ## Possible returns * `Jurisdiction` `Jurisdiction` — A geographic area or "zone" in which a rate or set of rates applies. - `adminArea1` `String` **nullable** — The highest level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. - `adminArea2` `String` **nullable** — The city, town, or village. - `adminArea3` `String` **nullable** — The sub-locality, suburb, neighborhood, or district. - `adminArea4` `String` **nullable** — The neighborhood, ward, or district. - `countryCode` `String!` **non-null** — The country code of the address. - `createdAt` `DateTime!` **non-null** — The data & time at which the jurisdiction was created. - `id` `ID!` **non-null** — The globally-unique ID. - `metafields` `JurisdictionMetafieldsConnection` **nullable** - `postalCode` `String` **nullable** — The postal code of the address. - `rates` `JurisdictionRatesConnection` **nullable** — The rates associated with the jurisdiction. - `updatedAt` `DateTime!` **non-null** — The data & time at which the jurisdiction was last updated. # jurisdiction (https://developer.godaddy.com/en/docs/references/rest/taxes/jurisdiction/queries/jurisdiction) --- title: jurisdiction description: Get a single jurisdiction. full: true --- query Requires `commerce.tax:read`. Get a single jurisdiction. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `ID!` **required** — The jurisdiction ID. ## Possible returns * `Jurisdiction` `Jurisdiction` — A geographic area or "zone" in which a rate or set of rates applies. - `adminArea1` `String` **nullable** — The highest level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. - `adminArea2` `String` **nullable** — The city, town, or village. - `adminArea3` `String` **nullable** — The sub-locality, suburb, neighborhood, or district. - `adminArea4` `String` **nullable** — The neighborhood, ward, or district. - `countryCode` `String!` **non-null** — The country code of the address. - `createdAt` `DateTime!` **non-null** — The data & time at which the jurisdiction was created. - `id` `ID!` **non-null** — The globally-unique ID. - `metafields` `JurisdictionMetafieldsConnection` **nullable** - `postalCode` `String` **nullable** — The postal code of the address. - `rates` `JurisdictionRatesConnection` **nullable** — The rates associated with the jurisdiction. - `updatedAt` `DateTime!` **non-null** — The data & time at which the jurisdiction was last updated. # jurisdictions (https://developer.godaddy.com/en/docs/references/rest/taxes/jurisdiction/queries/jurisdictions) --- title: jurisdictions description: Get a collection of jurisdictions. full: true --- query Requires `commerce.tax:read`. Get a collection of jurisdictions. `orderBy` is one key only (`id`, `createdAt`, or `updatedAt` — no `name`). Direction must be `ASC` or `DESC`. Sending two keys, or `"desc"`, fails validation. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `after` `String` **optional** * `before` `String` **optional** * `first` `Int` **optional** * `id` `JurisdictionIdFilter` **optional** * `in` `[ID!]` **optional** * `last` `Int` **optional** * `orderBy` `JurisdictionOrderBy` **optional** * `createdAt` `OrderByDirectionEnum` **optional** * `id` `OrderByDirectionEnum` **optional** * `updatedAt` `OrderByDirectionEnum` **optional** ## Possible returns * `QueryJurisdictionsConnection` `QueryJurisdictionsConnection` - `edges` `[QueryJurisdictionsConnectionEdge]` **nullable** - `pageInfo` `PageInfo!` **non-null** # activateOverride (https://developer.godaddy.com/en/docs/references/rest/taxes/override/mutations/activateOverride) --- title: activateOverride description: Activate an existing override. full: true --- mutation Requires `commerce.tax:write`. Activate an existing override. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `ID!` **required** ## Possible returns * `Override` `Override` — A rule to override any other taxation criteria for the associated skus, groups, or lists. - `activatedAt` `DateTime` **nullable** — The data & time at which the override was last activated. - `createdAt` `DateTime!` **non-null** — The data & time at which the override was created. - `customRate` `OverrideCustomRate` **nullable** - `description` `String` **nullable** — The human-friendly description. - `id` `ID!` **non-null** — The globally-unique ID. - `label` `String!` **non-null** — The label for display. - `lists` `OverrideListsConnection` **nullable** — The catalog lists to which the override applies. - `metafields` `OverrideMetafieldsConnection` **nullable** - `name` `String!` **non-null** — The unique human-friendly identifier. - `rates` `OverrideRatesConnection` **nullable** — The rates associated with the override. - `references` `OverrideReferencesConnection` **nullable** — A reference to a resource in an external service. - `skuGroups` `OverrideSkuGroupsConnection` **nullable** — The catalog SKU groups to which the override applies. - `skus` `OverrideSkusConnection` **nullable** — The catalog SKUs to which the override applies. - `status` `OverrideStatusEnum!` **non-null** — The current status. - `targetRate` `Rate` **nullable** — The rate that this override targets. - `updatedAt` `DateTime!` **non-null** — The data & time at which the override was last updated. # addListsToOverride (https://developer.godaddy.com/en/docs/references/rest/taxes/override/mutations/addListsToOverride) --- title: addListsToOverride description: Add existing lists to an existing override. full: true --- mutation Requires `commerce.tax:write`. Add existing lists to an existing override. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `input` `MutationAddListsToOverrideInput!` **required** * `listIds` `[ID!]!` **required** * `overrideId` `ID!` **required** ## Possible returns * `Override` `Override` — A rule to override any other taxation criteria for the associated skus, groups, or lists. - `activatedAt` `DateTime` **nullable** — The data & time at which the override was last activated. - `createdAt` `DateTime!` **non-null** — The data & time at which the override was created. - `customRate` `OverrideCustomRate` **nullable** - `description` `String` **nullable** — The human-friendly description. - `id` `ID!` **non-null** — The globally-unique ID. - `label` `String!` **non-null** — The label for display. - `lists` `OverrideListsConnection` **nullable** — The catalog lists to which the override applies. - `metafields` `OverrideMetafieldsConnection` **nullable** - `name` `String!` **non-null** — The unique human-friendly identifier. - `rates` `OverrideRatesConnection` **nullable** — The rates associated with the override. - `references` `OverrideReferencesConnection` **nullable** — A reference to a resource in an external service. - `skuGroups` `OverrideSkuGroupsConnection` **nullable** — The catalog SKU groups to which the override applies. - `skus` `OverrideSkusConnection` **nullable** — The catalog SKUs to which the override applies. - `status` `OverrideStatusEnum!` **non-null** — The current status. - `targetRate` `Rate` **nullable** — The rate that this override targets. - `updatedAt` `DateTime!` **non-null** — The data & time at which the override was last updated. # addRatesToOverride (https://developer.godaddy.com/en/docs/references/rest/taxes/override/mutations/addRatesToOverride) --- title: addRatesToOverride description: Add existing rates to an existing override. full: true --- mutation Requires `commerce.tax:write`. Add existing rates to an existing override. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `input` `MutationAddRatesToOverrideInput!` **required** * `rateIds` `[ID!]!` **required** * `overrideId` `ID!` **required** ## Possible returns * `Override` `Override` — A rule to override any other taxation criteria for the associated skus, groups, or lists. - `activatedAt` `DateTime` **nullable** — The data & time at which the override was last activated. - `createdAt` `DateTime!` **non-null** — The data & time at which the override was created. - `customRate` `OverrideCustomRate` **nullable** - `description` `String` **nullable** — The human-friendly description. - `id` `ID!` **non-null** — The globally-unique ID. - `label` `String!` **non-null** — The label for display. - `lists` `OverrideListsConnection` **nullable** — The catalog lists to which the override applies. - `metafields` `OverrideMetafieldsConnection` **nullable** - `name` `String!` **non-null** — The unique human-friendly identifier. - `rates` `OverrideRatesConnection` **nullable** — The rates associated with the override. - `references` `OverrideReferencesConnection` **nullable** — A reference to a resource in an external service. - `skuGroups` `OverrideSkuGroupsConnection` **nullable** — The catalog SKU groups to which the override applies. - `skus` `OverrideSkusConnection` **nullable** — The catalog SKUs to which the override applies. - `status` `OverrideStatusEnum!` **non-null** — The current status. - `targetRate` `Rate` **nullable** — The rate that this override targets. - `updatedAt` `DateTime!` **non-null** — The data & time at which the override was last updated. # addSkuGroupsToOverride (https://developer.godaddy.com/en/docs/references/rest/taxes/override/mutations/addSkuGroupsToOverride) --- title: addSkuGroupsToOverride description: Add existing SKU groups to an existing override. full: true --- mutation Requires `commerce.tax:write`. Add existing SKU groups to an existing override. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `input` `MutationAddSkuGroupsToOverrideInput!` **required** * `skuGroupIds` `[ID!]!` **required** * `overrideId` `ID!` **required** ## Possible returns * `Override` `Override` — A rule to override any other taxation criteria for the associated skus, groups, or lists. - `activatedAt` `DateTime` **nullable** — The data & time at which the override was last activated. - `createdAt` `DateTime!` **non-null** — The data & time at which the override was created. - `customRate` `OverrideCustomRate` **nullable** - `description` `String` **nullable** — The human-friendly description. - `id` `ID!` **non-null** — The globally-unique ID. - `label` `String!` **non-null** — The label for display. - `lists` `OverrideListsConnection` **nullable** — The catalog lists to which the override applies. - `metafields` `OverrideMetafieldsConnection` **nullable** - `name` `String!` **non-null** — The unique human-friendly identifier. - `rates` `OverrideRatesConnection` **nullable** — The rates associated with the override. - `references` `OverrideReferencesConnection` **nullable** — A reference to a resource in an external service. - `skuGroups` `OverrideSkuGroupsConnection` **nullable** — The catalog SKU groups to which the override applies. - `skus` `OverrideSkusConnection` **nullable** — The catalog SKUs to which the override applies. - `status` `OverrideStatusEnum!` **non-null** — The current status. - `targetRate` `Rate` **nullable** — The rate that this override targets. - `updatedAt` `DateTime!` **non-null** — The data & time at which the override was last updated. # addSkusToOverride (https://developer.godaddy.com/en/docs/references/rest/taxes/override/mutations/addSkusToOverride) --- title: addSkusToOverride description: Add existing SKUs to an existing override. full: true --- mutation Requires `commerce.tax:write`. Add existing SKUs to an existing override. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `input` `MutationAddSkusToOverrideInput!` **required** * `skuIds` `[ID!]!` **required** * `overrideId` `ID!` **required** ## Possible returns * `Override` `Override` — A rule to override any other taxation criteria for the associated skus, groups, or lists. - `activatedAt` `DateTime` **nullable** — The data & time at which the override was last activated. - `createdAt` `DateTime!` **non-null** — The data & time at which the override was created. - `customRate` `OverrideCustomRate` **nullable** - `description` `String` **nullable** — The human-friendly description. - `id` `ID!` **non-null** — The globally-unique ID. - `label` `String!` **non-null** — The label for display. - `lists` `OverrideListsConnection` **nullable** — The catalog lists to which the override applies. - `metafields` `OverrideMetafieldsConnection` **nullable** - `name` `String!` **non-null** — The unique human-friendly identifier. - `rates` `OverrideRatesConnection` **nullable** — The rates associated with the override. - `references` `OverrideReferencesConnection` **nullable** — A reference to a resource in an external service. - `skuGroups` `OverrideSkuGroupsConnection` **nullable** — The catalog SKU groups to which the override applies. - `skus` `OverrideSkusConnection` **nullable** — The catalog SKUs to which the override applies. - `status` `OverrideStatusEnum!` **non-null** — The current status. - `targetRate` `Rate` **nullable** — The rate that this override targets. - `updatedAt` `DateTime!` **non-null** — The data & time at which the override was last updated. # createOverride (https://developer.godaddy.com/en/docs/references/rest/taxes/override/mutations/createOverride) --- title: createOverride description: Create a new override. full: true --- mutation Requires `commerce.tax:create`. Create a new override. `metafields` and `references` are optional — omit them. If you send `metafields`, the array must be nonempty; `[]` is rejected. Prefer `type: "string"` (lowercase). For `SimpleMoneyInput.value`, send `1999` for $19.99 USD, not `19.99`. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `input` `MutationCreateOverrideInput!` **required** * `label` `String!` **required** — A label for display. * `createdAt` `DateTime` **optional** — WARNING: DO NOT USE. Deprecated: This field is deprecated and only used for Tax v1 to v2 migration syncs. * `customRate` `OverrideCustomRateCreateInput` **optional** — A custom rate to be applied by the override. * `value` `RateValueInput!` **required** — The custom rate's value. * `calculationMethod` `OverrideCalculationMethodEnum` **optional** — The method to be used when applying the custom rate to a purchase amount. * `description` `String` **optional** — A human-friendly description. * `metafields` `[CreateMetafieldInput!]` **optional** — Any metafields to be created and assigned to the new override. * `key` `String!` **required** * `namespace` `String!` **required** * `type` `String!` **required** — Metafield value type. Live catalog validation accepts lowercase values such as `boolean`, `string`, `stringMultiLine`, `number`, `numberDecimal`, `date`, `dateTime`, `json`, `measurement`, `url`, `reference`, `money`, `list.string`, `list.number`, `list.numberDecimal`. Uppercase `STRING` is rejected. * `value` `String!` **required** * `name` `String` **optional** — A unique human-friendly identifier. If omitted, a name will be generated from the `label` value. * `references` `[CreateReferenceInput!]` **optional** — Any references to be created and assigned to the new override. * `origin` `String!` **required** — The origin of the reference. * `value` `String!` **required** — The value of the reference. * `status` `OverrideStatusEnum` **optional** — The desired status. * `targetRateId` `ID` **optional** — The ID of the target rate that this override references. * `updatedAt` `DateTime` **optional** — WARNING: DO NOT USE. Deprecated: This field is deprecated and only used for Tax v1 to v2 migration syncs. ## Possible returns * `Override` `Override` — A rule to override any other taxation criteria for the associated skus, groups, or lists. - `activatedAt` `DateTime` **nullable** — The data & time at which the override was last activated. - `createdAt` `DateTime!` **non-null** — The data & time at which the override was created. - `customRate` `OverrideCustomRate` **nullable** - `description` `String` **nullable** — The human-friendly description. - `id` `ID!` **non-null** — The globally-unique ID. - `label` `String!` **non-null** — The label for display. - `lists` `OverrideListsConnection` **nullable** — The catalog lists to which the override applies. - `metafields` `OverrideMetafieldsConnection` **nullable** - `name` `String!` **non-null** — The unique human-friendly identifier. - `rates` `OverrideRatesConnection` **nullable** — The rates associated with the override. - `references` `OverrideReferencesConnection` **nullable** — A reference to a resource in an external service. - `skuGroups` `OverrideSkuGroupsConnection` **nullable** — The catalog SKU groups to which the override applies. - `skus` `OverrideSkusConnection` **nullable** — The catalog SKUs to which the override applies. - `status` `OverrideStatusEnum!` **non-null** — The current status. - `targetRate` `Rate` **nullable** — The rate that this override targets. - `updatedAt` `DateTime!` **non-null** — The data & time at which the override was last updated. # createReferencesForOverride (https://developer.godaddy.com/en/docs/references/rest/taxes/override/mutations/createReferencesForOverride) --- title: createReferencesForOverride description: Create references for an existing override. full: true --- mutation Requires `commerce.tax:create`. Create references for an existing override. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `ID!` **required** * `input` `MutationCreateReferencesForOverrideInput!` **required** * `references` `[CreateReferenceInput!]!` **required** * `origin` `String!` **required** — The origin of the reference. * `value` `String!` **required** — The value of the reference. ## Possible returns * `Override` `Override` — A rule to override any other taxation criteria for the associated skus, groups, or lists. - `activatedAt` `DateTime` **nullable** — The data & time at which the override was last activated. - `createdAt` `DateTime!` **non-null** — The data & time at which the override was created. - `customRate` `OverrideCustomRate` **nullable** - `description` `String` **nullable** — The human-friendly description. - `id` `ID!` **non-null** — The globally-unique ID. - `label` `String!` **non-null** — The label for display. - `lists` `OverrideListsConnection` **nullable** — The catalog lists to which the override applies. - `metafields` `OverrideMetafieldsConnection` **nullable** - `name` `String!` **non-null** — The unique human-friendly identifier. - `rates` `OverrideRatesConnection` **nullable** — The rates associated with the override. - `references` `OverrideReferencesConnection` **nullable** — A reference to a resource in an external service. - `skuGroups` `OverrideSkuGroupsConnection` **nullable** — The catalog SKU groups to which the override applies. - `skus` `OverrideSkusConnection` **nullable** — The catalog SKUs to which the override applies. - `status` `OverrideStatusEnum!` **non-null** — The current status. - `targetRate` `Rate` **nullable** — The rate that this override targets. - `updatedAt` `DateTime!` **non-null** — The data & time at which the override was last updated. # deactivateOverride (https://developer.godaddy.com/en/docs/references/rest/taxes/override/mutations/deactivateOverride) --- title: deactivateOverride description: Deactivate an existing override. full: true --- mutation Requires `commerce.tax:write`. Deactivate an existing override. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `ID!` **required** ## Possible returns * `Override` `Override` — A rule to override any other taxation criteria for the associated skus, groups, or lists. - `activatedAt` `DateTime` **nullable** — The data & time at which the override was last activated. - `createdAt` `DateTime!` **non-null** — The data & time at which the override was created. - `customRate` `OverrideCustomRate` **nullable** - `description` `String` **nullable** — The human-friendly description. - `id` `ID!` **non-null** — The globally-unique ID. - `label` `String!` **non-null** — The label for display. - `lists` `OverrideListsConnection` **nullable** — The catalog lists to which the override applies. - `metafields` `OverrideMetafieldsConnection` **nullable** - `name` `String!` **non-null** — The unique human-friendly identifier. - `rates` `OverrideRatesConnection` **nullable** — The rates associated with the override. - `references` `OverrideReferencesConnection` **nullable** — A reference to a resource in an external service. - `skuGroups` `OverrideSkuGroupsConnection` **nullable** — The catalog SKU groups to which the override applies. - `skus` `OverrideSkusConnection` **nullable** — The catalog SKUs to which the override applies. - `status` `OverrideStatusEnum!` **non-null** — The current status. - `targetRate` `Rate` **nullable** — The rate that this override targets. - `updatedAt` `DateTime!` **non-null** — The data & time at which the override was last updated. # deleteOverride (https://developer.godaddy.com/en/docs/references/rest/taxes/override/mutations/deleteOverride) --- title: deleteOverride description: Delete an existing override. full: true --- mutation Requires `commerce.tax:delete`. Delete an existing override. Returns the deleted `Override`. Selecting no subfields is a GraphQL validation error. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `ID!` **required** ## Possible returns * `Override` `Override` — A rule to override any other taxation criteria for the associated skus, groups, or lists. - `activatedAt` `DateTime` **nullable** — The data & time at which the override was last activated. - `createdAt` `DateTime!` **non-null** — The data & time at which the override was created. - `customRate` `OverrideCustomRate` **nullable** - `description` `String` **nullable** — The human-friendly description. - `id` `ID!` **non-null** — The globally-unique ID. - `label` `String!` **non-null** — The label for display. - `lists` `OverrideListsConnection` **nullable** — The catalog lists to which the override applies. - `metafields` `OverrideMetafieldsConnection` **nullable** - `name` `String!` **non-null** — The unique human-friendly identifier. - `rates` `OverrideRatesConnection` **nullable** — The rates associated with the override. - `references` `OverrideReferencesConnection` **nullable** — A reference to a resource in an external service. - `skuGroups` `OverrideSkuGroupsConnection` **nullable** — The catalog SKU groups to which the override applies. - `skus` `OverrideSkusConnection` **nullable** — The catalog SKUs to which the override applies. - `status` `OverrideStatusEnum!` **non-null** — The current status. - `targetRate` `Rate` **nullable** — The rate that this override targets. - `updatedAt` `DateTime!` **non-null** — The data & time at which the override was last updated. # deleteReferencesFromOverride (https://developer.godaddy.com/en/docs/references/rest/taxes/override/mutations/deleteReferencesFromOverride) --- title: deleteReferencesFromOverride description: Delete references from an existing override. full: true --- mutation Requires `commerce.tax:delete`. Delete references from an existing override. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `ID!` **required** * `input` `MutationDeleteReferencesFromOverrideInput!` **required** * `referenceIds` `[ID!]!` **required** ## Possible returns * `Override` `Override` — A rule to override any other taxation criteria for the associated skus, groups, or lists. - `activatedAt` `DateTime` **nullable** — The data & time at which the override was last activated. - `createdAt` `DateTime!` **non-null** — The data & time at which the override was created. - `customRate` `OverrideCustomRate` **nullable** - `description` `String` **nullable** — The human-friendly description. - `id` `ID!` **non-null** — The globally-unique ID. - `label` `String!` **non-null** — The label for display. - `lists` `OverrideListsConnection` **nullable** — The catalog lists to which the override applies. - `metafields` `OverrideMetafieldsConnection` **nullable** - `name` `String!` **non-null** — The unique human-friendly identifier. - `rates` `OverrideRatesConnection` **nullable** — The rates associated with the override. - `references` `OverrideReferencesConnection` **nullable** — A reference to a resource in an external service. - `skuGroups` `OverrideSkuGroupsConnection` **nullable** — The catalog SKU groups to which the override applies. - `skus` `OverrideSkusConnection` **nullable** — The catalog SKUs to which the override applies. - `status` `OverrideStatusEnum!` **non-null** — The current status. - `targetRate` `Rate` **nullable** — The rate that this override targets. - `updatedAt` `DateTime!` **non-null** — The data & time at which the override was last updated. # removeListsFromOverride (https://developer.godaddy.com/en/docs/references/rest/taxes/override/mutations/removeListsFromOverride) --- title: removeListsFromOverride description: Remove existing lists from an existing override. full: true --- mutation Requires `commerce.tax:write`. Remove existing lists from an existing override. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `input` `MutationRemoveListsFromOverrideInput!` **required** * `listIds` `[ID!]!` **required** * `overrideId` `ID!` **required** ## Possible returns * `Override` `Override` — A rule to override any other taxation criteria for the associated skus, groups, or lists. - `activatedAt` `DateTime` **nullable** — The data & time at which the override was last activated. - `createdAt` `DateTime!` **non-null** — The data & time at which the override was created. - `customRate` `OverrideCustomRate` **nullable** - `description` `String` **nullable** — The human-friendly description. - `id` `ID!` **non-null** — The globally-unique ID. - `label` `String!` **non-null** — The label for display. - `lists` `OverrideListsConnection` **nullable** — The catalog lists to which the override applies. - `metafields` `OverrideMetafieldsConnection` **nullable** - `name` `String!` **non-null** — The unique human-friendly identifier. - `rates` `OverrideRatesConnection` **nullable** — The rates associated with the override. - `references` `OverrideReferencesConnection` **nullable** — A reference to a resource in an external service. - `skuGroups` `OverrideSkuGroupsConnection` **nullable** — The catalog SKU groups to which the override applies. - `skus` `OverrideSkusConnection` **nullable** — The catalog SKUs to which the override applies. - `status` `OverrideStatusEnum!` **non-null** — The current status. - `targetRate` `Rate` **nullable** — The rate that this override targets. - `updatedAt` `DateTime!` **non-null** — The data & time at which the override was last updated. # removeRatesFromOverride (https://developer.godaddy.com/en/docs/references/rest/taxes/override/mutations/removeRatesFromOverride) --- title: removeRatesFromOverride description: Remove existing rates from an existing override. full: true --- mutation Requires `commerce.tax:write`. Remove existing rates from an existing override. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `input` `MutationRemoveRatesFromOverrideInput!` **required** * `rateIds` `[ID!]!` **required** * `overrideId` `ID!` **required** ## Possible returns * `Override` `Override` — A rule to override any other taxation criteria for the associated skus, groups, or lists. - `activatedAt` `DateTime` **nullable** — The data & time at which the override was last activated. - `createdAt` `DateTime!` **non-null** — The data & time at which the override was created. - `customRate` `OverrideCustomRate` **nullable** - `description` `String` **nullable** — The human-friendly description. - `id` `ID!` **non-null** — The globally-unique ID. - `label` `String!` **non-null** — The label for display. - `lists` `OverrideListsConnection` **nullable** — The catalog lists to which the override applies. - `metafields` `OverrideMetafieldsConnection` **nullable** - `name` `String!` **non-null** — The unique human-friendly identifier. - `rates` `OverrideRatesConnection` **nullable** — The rates associated with the override. - `references` `OverrideReferencesConnection` **nullable** — A reference to a resource in an external service. - `skuGroups` `OverrideSkuGroupsConnection` **nullable** — The catalog SKU groups to which the override applies. - `skus` `OverrideSkusConnection` **nullable** — The catalog SKUs to which the override applies. - `status` `OverrideStatusEnum!` **non-null** — The current status. - `targetRate` `Rate` **nullable** — The rate that this override targets. - `updatedAt` `DateTime!` **non-null** — The data & time at which the override was last updated. # removeSkusFromOverride (https://developer.godaddy.com/en/docs/references/rest/taxes/override/mutations/removeSkusFromOverride) --- title: removeSkusFromOverride description: Remove existing SKUs from an existing override. full: true --- mutation Requires `commerce.tax:write`. Remove existing SKUs from an existing override. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `input` `MutationRemoveSkusFromOverrideInput!` **required** * `skuIds` `[ID!]!` **required** * `overrideId` `ID!` **required** ## Possible returns * `Override` `Override` — A rule to override any other taxation criteria for the associated skus, groups, or lists. - `activatedAt` `DateTime` **nullable** — The data & time at which the override was last activated. - `createdAt` `DateTime!` **non-null** — The data & time at which the override was created. - `customRate` `OverrideCustomRate` **nullable** - `description` `String` **nullable** — The human-friendly description. - `id` `ID!` **non-null** — The globally-unique ID. - `label` `String!` **non-null** — The label for display. - `lists` `OverrideListsConnection` **nullable** — The catalog lists to which the override applies. - `metafields` `OverrideMetafieldsConnection` **nullable** - `name` `String!` **non-null** — The unique human-friendly identifier. - `rates` `OverrideRatesConnection` **nullable** — The rates associated with the override. - `references` `OverrideReferencesConnection` **nullable** — A reference to a resource in an external service. - `skuGroups` `OverrideSkuGroupsConnection` **nullable** — The catalog SKU groups to which the override applies. - `skus` `OverrideSkusConnection` **nullable** — The catalog SKUs to which the override applies. - `status` `OverrideStatusEnum!` **non-null** — The current status. - `targetRate` `Rate` **nullable** — The rate that this override targets. - `updatedAt` `DateTime!` **non-null** — The data & time at which the override was last updated. # removeSkusGroupsFromOverride (https://developer.godaddy.com/en/docs/references/rest/taxes/override/mutations/removeSkusGroupsFromOverride) --- title: removeSkusGroupsFromOverride description: Remove existing SKU groups from an existing override. full: true --- mutation Requires `commerce.tax:write`. Remove existing SKU groups from an existing override. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `input` `MutationRemoveSkusGroupsFromOverrideInput!` **required** * `skuGroupIds` `[ID!]!` **required** * `overrideId` `ID!` **required** ## Possible returns * `Override` `Override` — A rule to override any other taxation criteria for the associated skus, groups, or lists. - `activatedAt` `DateTime` **nullable** — The data & time at which the override was last activated. - `createdAt` `DateTime!` **non-null** — The data & time at which the override was created. - `customRate` `OverrideCustomRate` **nullable** - `description` `String` **nullable** — The human-friendly description. - `id` `ID!` **non-null** — The globally-unique ID. - `label` `String!` **non-null** — The label for display. - `lists` `OverrideListsConnection` **nullable** — The catalog lists to which the override applies. - `metafields` `OverrideMetafieldsConnection` **nullable** - `name` `String!` **non-null** — The unique human-friendly identifier. - `rates` `OverrideRatesConnection` **nullable** — The rates associated with the override. - `references` `OverrideReferencesConnection` **nullable** — A reference to a resource in an external service. - `skuGroups` `OverrideSkuGroupsConnection` **nullable** — The catalog SKU groups to which the override applies. - `skus` `OverrideSkusConnection` **nullable** — The catalog SKUs to which the override applies. - `status` `OverrideStatusEnum!` **non-null** — The current status. - `targetRate` `Rate` **nullable** — The rate that this override targets. - `updatedAt` `DateTime!` **non-null** — The data & time at which the override was last updated. # updateOverride (https://developer.godaddy.com/en/docs/references/rest/taxes/override/mutations/updateOverride) --- title: updateOverride description: Update an existing override. full: true --- mutation Requires `commerce.tax:write`. Update an existing override. For `SimpleMoneyInput.value`, send `1999` for $19.99 USD, not `19.99`. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `ID!` **required** * `input` `MutationUpdateOverrideInput!` **required** * `createdAt` `DateTime` **optional** — WARNING: DO NOT USE. Deprecated: This field is deprecated and only used for Tax v1 to v2 migration syncs. * `customRate` `OverrideCustomRateUpdateInput` **optional** — A custom rate to be applied by the override. * `value` `RateValueInput!` **required** — The custom rate's value. * `calculationMethod` `OverrideCalculationMethodEnum` **optional** — The method to be used when applying the custom rate to a purchase amount. * `description` `String` **optional** — A human-friendly description. * `label` `String` **optional** — A label for display. * `name` `String` **optional** — A unique human-friendly identifier. * `status` `OverrideStatusEnum` **optional** — The desired status. * `targetRateId` `ID` **optional** — The ID of the target rate that this override references. * `updatedAt` `DateTime` **optional** — WARNING: DO NOT USE. Deprecated: This field is deprecated and only used for Tax v1 to v2 migration syncs. ## Possible returns * `Override` `Override` — A rule to override any other taxation criteria for the associated skus, groups, or lists. - `activatedAt` `DateTime` **nullable** — The data & time at which the override was last activated. - `createdAt` `DateTime!` **non-null** — The data & time at which the override was created. - `customRate` `OverrideCustomRate` **nullable** - `description` `String` **nullable** — The human-friendly description. - `id` `ID!` **non-null** — The globally-unique ID. - `label` `String!` **non-null** — The label for display. - `lists` `OverrideListsConnection` **nullable** — The catalog lists to which the override applies. - `metafields` `OverrideMetafieldsConnection` **nullable** - `name` `String!` **non-null** — The unique human-friendly identifier. - `rates` `OverrideRatesConnection` **nullable** — The rates associated with the override. - `references` `OverrideReferencesConnection` **nullable** — A reference to a resource in an external service. - `skuGroups` `OverrideSkuGroupsConnection` **nullable** — The catalog SKU groups to which the override applies. - `skus` `OverrideSkusConnection` **nullable** — The catalog SKUs to which the override applies. - `status` `OverrideStatusEnum!` **non-null** — The current status. - `targetRate` `Rate` **nullable** — The rate that this override targets. - `updatedAt` `DateTime!` **non-null** — The data & time at which the override was last updated. # override (https://developer.godaddy.com/en/docs/references/rest/taxes/override/queries/override) --- title: override description: Get a single override. full: true --- query Requires `commerce.tax:read`. Get a single override. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `ID!` **required** — The override ID. ## Possible returns * `Override` `Override` — A rule to override any other taxation criteria for the associated skus, groups, or lists. - `activatedAt` `DateTime` **nullable** — The data & time at which the override was last activated. - `createdAt` `DateTime!` **non-null** — The data & time at which the override was created. - `customRate` `OverrideCustomRate` **nullable** - `description` `String` **nullable** — The human-friendly description. - `id` `ID!` **non-null** — The globally-unique ID. - `label` `String!` **non-null** — The label for display. - `lists` `OverrideListsConnection` **nullable** — The catalog lists to which the override applies. - `metafields` `OverrideMetafieldsConnection` **nullable** - `name` `String!` **non-null** — The unique human-friendly identifier. - `rates` `OverrideRatesConnection` **nullable** — The rates associated with the override. - `references` `OverrideReferencesConnection` **nullable** — A reference to a resource in an external service. - `skuGroups` `OverrideSkuGroupsConnection` **nullable** — The catalog SKU groups to which the override applies. - `skus` `OverrideSkusConnection` **nullable** — The catalog SKUs to which the override applies. - `status` `OverrideStatusEnum!` **non-null** — The current status. - `targetRate` `Rate` **nullable** — The rate that this override targets. - `updatedAt` `DateTime!` **non-null** — The data & time at which the override was last updated. # overrides (https://developer.godaddy.com/en/docs/references/rest/taxes/override/queries/overrides) --- title: overrides description: Get a collection of overrides. full: true --- query Requires `commerce.tax:read`. Get a collection of overrides. `orderBy` is one key only (`id`, `createdAt`, or `updatedAt` — no `name`). Direction must be `ASC` or `DESC`. Sending two keys, or `"desc"`, fails validation. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `after` `String` **optional** * `before` `String` **optional** * `first` `Int` **optional** * `id` `OverrideIdFilter` **optional** * `in` `[ID!]` **optional** * `last` `Int` **optional** * `orderBy` `OverrideOrderBy` **optional** * `createdAt` `OrderByDirectionEnum` **optional** * `id` `OrderByDirectionEnum` **optional** * `updatedAt` `OrderByDirectionEnum` **optional** * `referenceValue` `ReferenceValueFilter` **optional** * `in` `[String!]` **optional** ## Possible returns * `QueryOverridesConnection` `QueryOverridesConnection` - `edges` `[QueryOverridesConnectionEdge]` **nullable** - `pageInfo` `PageInfo!` **non-null** # activateRate (https://developer.godaddy.com/en/docs/references/rest/taxes/rate/mutations/activateRate) --- title: activateRate description: Activate an existing rate. full: true --- mutation Requires `commerce.tax:write`. Activate an existing rate. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `ID!` **required** ## Possible returns * `Rate` `Rate` — An individual tax rate. - `activatedAt` `DateTime` **nullable** — The data & time at which the rate was first activated. - `calculationMethod` `RateCalculationMethodEnum!` **non-null** — The method to be used when applying the rate to a purchase amount. - `classifications` `RateClassificationsConnection` **nullable** — The classifications associated with the rate. - `createdAt` `DateTime!` **non-null** — The data & time at which the rate was created. - `description` `String` **nullable** — The human-friendly description. - `id` `ID!` **non-null** — The globally-unique ID. - `jurisdiction` `Jurisdiction` **nullable** — The jurisdiction in which this rate applies. - `label` `String!` **non-null** — The label for display. - `metafields` `RateMetafieldsConnection` **nullable** - `name` `String!` **non-null** — The unique human-friendly identifier. - `references` `RateReferencesConnection` **nullable** — A reference to the resource in an external service. - `status` `RateStatusEnum!` **non-null** — The current status. - `updatedAt` `DateTime!` **non-null** — The data & time at which the rate was last updated. - `value` `RateValue!` **non-null** — The rate's value # createRate (https://developer.godaddy.com/en/docs/references/rest/taxes/rate/mutations/createRate) --- title: createRate description: Create a new rate. full: true --- mutation Requires `commerce.tax:create`. Create a new rate. `value` is a union. Select `value { __typename ... on RatePercentage { percentage } ... on RateAmount { amount { value currencyCode } } }`. There is no `value { rate }` field. `metafields` and `references` are optional — omit them. If you send `metafields`, the array must be nonempty; `[]` is rejected. Prefer `type: "string"` (lowercase). For `SimpleMoneyInput.value`, send `1999` for $19.99 USD, not `19.99`. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `input` `MutationCreateRateInput!` **required** * `label` `String!` **required** — A label for display. * `value` `RateValueInput!` **required** — The rate's value. Set `percentage` or `amount`, not both. For `amount.value` use integer minor units. * `amount` `SimpleMoneyInput` **optional** — The rate value represented as a fixed money amount. Required if `percentage` is not provided. * `percentage` `String` **optional** — The percentage applied by the rate, out of 100. Required if `amount` is not provided. * `calculationMethod` `RateCalculationMethodEnum` **optional** — The method to be used when applying the rate to a purchase amount. * `createdAt` `DateTime` **optional** — WARNING: DO NOT USE. Deprecated: This field is deprecated and only used for Tax v1 to v2 migration syncs. * `description` `String` **optional** — A human-friendly description. * `jurisdictionId` `ID` **optional** — The ID of the jurisdiction in which this rate applies. * `metafields` `[CreateMetafieldInput!]` **optional** — Any metafields to be created and assigned to the new rate. * `key` `String!` **required** * `namespace` `String!` **required** * `type` `String!` **required** — Metafield value type. Live catalog validation accepts lowercase values such as `boolean`, `string`, `stringMultiLine`, `number`, `numberDecimal`, `date`, `dateTime`, `json`, `measurement`, `url`, `reference`, `money`, `list.string`, `list.number`, `list.numberDecimal`. Uppercase `STRING` is rejected. * `value` `String!` **required** * `name` `String` **optional** — A unique human-friendly identifier. If omitted, a name will be generated from the `label` value. * `references` `[CreateReferenceInput!]` **optional** — Any references to be created and assigned to the new rate. * `origin` `String!` **required** — The origin of the reference. * `value` `String!` **required** — The value of the reference. * `status` `RateStatusEnum` **optional** — The desired status. * `updatedAt` `DateTime` **optional** — WARNING: DO NOT USE. Deprecated: This field is deprecated and only used for Tax v1 to v2 migration syncs. ## Possible returns * `Rate` `Rate` — An individual tax rate. - `activatedAt` `DateTime` **nullable** — The data & time at which the rate was first activated. - `calculationMethod` `RateCalculationMethodEnum!` **non-null** — The method to be used when applying the rate to a purchase amount. - `classifications` `RateClassificationsConnection` **nullable** — The classifications associated with the rate. - `createdAt` `DateTime!` **non-null** — The data & time at which the rate was created. - `description` `String` **nullable** — The human-friendly description. - `id` `ID!` **non-null** — The globally-unique ID. - `jurisdiction` `Jurisdiction` **nullable** — The jurisdiction in which this rate applies. - `label` `String!` **non-null** — The label for display. - `metafields` `RateMetafieldsConnection` **nullable** - `name` `String!` **non-null** — The unique human-friendly identifier. - `references` `RateReferencesConnection` **nullable** — A reference to the resource in an external service. - `status` `RateStatusEnum!` **non-null** — The current status. - `updatedAt` `DateTime!` **non-null** — The data & time at which the rate was last updated. - `value` `RateValue!` **non-null** — The rate's value # createReferencesForRate (https://developer.godaddy.com/en/docs/references/rest/taxes/rate/mutations/createReferencesForRate) --- title: createReferencesForRate description: Create references for an existing rate. full: true --- mutation Requires `commerce.tax:create`. Create references for an existing rate. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `ID!` **required** * `input` `MutationCreateReferencesForRateInput!` **required** * `references` `[CreateReferenceInput!]!` **required** * `origin` `String!` **required** — The origin of the reference. * `value` `String!` **required** — The value of the reference. ## Possible returns * `Rate` `Rate` — An individual tax rate. - `activatedAt` `DateTime` **nullable** — The data & time at which the rate was first activated. - `calculationMethod` `RateCalculationMethodEnum!` **non-null** — The method to be used when applying the rate to a purchase amount. - `classifications` `RateClassificationsConnection` **nullable** — The classifications associated with the rate. - `createdAt` `DateTime!` **non-null** — The data & time at which the rate was created. - `description` `String` **nullable** — The human-friendly description. - `id` `ID!` **non-null** — The globally-unique ID. - `jurisdiction` `Jurisdiction` **nullable** — The jurisdiction in which this rate applies. - `label` `String!` **non-null** — The label for display. - `metafields` `RateMetafieldsConnection` **nullable** - `name` `String!` **non-null** — The unique human-friendly identifier. - `references` `RateReferencesConnection` **nullable** — A reference to the resource in an external service. - `status` `RateStatusEnum!` **non-null** — The current status. - `updatedAt` `DateTime!` **non-null** — The data & time at which the rate was last updated. - `value` `RateValue!` **non-null** — The rate's value # deactivateRate (https://developer.godaddy.com/en/docs/references/rest/taxes/rate/mutations/deactivateRate) --- title: deactivateRate description: Deactivate an existing rate. full: true --- mutation Requires `commerce.tax:write`. Deactivate an existing rate. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `ID!` **required** ## Possible returns * `Rate` `Rate` — An individual tax rate. - `activatedAt` `DateTime` **nullable** — The data & time at which the rate was first activated. - `calculationMethod` `RateCalculationMethodEnum!` **non-null** — The method to be used when applying the rate to a purchase amount. - `classifications` `RateClassificationsConnection` **nullable** — The classifications associated with the rate. - `createdAt` `DateTime!` **non-null** — The data & time at which the rate was created. - `description` `String` **nullable** — The human-friendly description. - `id` `ID!` **non-null** — The globally-unique ID. - `jurisdiction` `Jurisdiction` **nullable** — The jurisdiction in which this rate applies. - `label` `String!` **non-null** — The label for display. - `metafields` `RateMetafieldsConnection` **nullable** - `name` `String!` **non-null** — The unique human-friendly identifier. - `references` `RateReferencesConnection` **nullable** — A reference to the resource in an external service. - `status` `RateStatusEnum!` **non-null** — The current status. - `updatedAt` `DateTime!` **non-null** — The data & time at which the rate was last updated. - `value` `RateValue!` **non-null** — The rate's value # deleteRate (https://developer.godaddy.com/en/docs/references/rest/taxes/rate/mutations/deleteRate) --- title: deleteRate description: Delete an existing rate. full: true --- mutation Requires `commerce.tax:delete`. Delete an existing rate. Returns the deleted `Rate`. Selecting no subfields is a GraphQL validation error. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `ID!` **required** ## Possible returns * `Rate` `Rate` — An individual tax rate. - `activatedAt` `DateTime` **nullable** — The data & time at which the rate was first activated. - `calculationMethod` `RateCalculationMethodEnum!` **non-null** — The method to be used when applying the rate to a purchase amount. - `classifications` `RateClassificationsConnection` **nullable** — The classifications associated with the rate. - `createdAt` `DateTime!` **non-null** — The data & time at which the rate was created. - `description` `String` **nullable** — The human-friendly description. - `id` `ID!` **non-null** — The globally-unique ID. - `jurisdiction` `Jurisdiction` **nullable** — The jurisdiction in which this rate applies. - `label` `String!` **non-null** — The label for display. - `metafields` `RateMetafieldsConnection` **nullable** - `name` `String!` **non-null** — The unique human-friendly identifier. - `references` `RateReferencesConnection` **nullable** — A reference to the resource in an external service. - `status` `RateStatusEnum!` **non-null** — The current status. - `updatedAt` `DateTime!` **non-null** — The data & time at which the rate was last updated. - `value` `RateValue!` **non-null** — The rate's value # deleteReferencesFromRate (https://developer.godaddy.com/en/docs/references/rest/taxes/rate/mutations/deleteReferencesFromRate) --- title: deleteReferencesFromRate description: Delete references from an existing rate. full: true --- mutation Requires `commerce.tax:delete`. Delete references from an existing rate. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `ID!` **required** * `input` `MutationDeleteReferencesFromRateInput!` **required** * `referenceIds` `[ID!]!` **required** ## Possible returns * `Rate` `Rate` — An individual tax rate. - `activatedAt` `DateTime` **nullable** — The data & time at which the rate was first activated. - `calculationMethod` `RateCalculationMethodEnum!` **non-null** — The method to be used when applying the rate to a purchase amount. - `classifications` `RateClassificationsConnection` **nullable** — The classifications associated with the rate. - `createdAt` `DateTime!` **non-null** — The data & time at which the rate was created. - `description` `String` **nullable** — The human-friendly description. - `id` `ID!` **non-null** — The globally-unique ID. - `jurisdiction` `Jurisdiction` **nullable** — The jurisdiction in which this rate applies. - `label` `String!` **non-null** — The label for display. - `metafields` `RateMetafieldsConnection` **nullable** - `name` `String!` **non-null** — The unique human-friendly identifier. - `references` `RateReferencesConnection` **nullable** — A reference to the resource in an external service. - `status` `RateStatusEnum!` **non-null** — The current status. - `updatedAt` `DateTime!` **non-null** — The data & time at which the rate was last updated. - `value` `RateValue!` **non-null** — The rate's value # updateRate (https://developer.godaddy.com/en/docs/references/rest/taxes/rate/mutations/updateRate) --- title: updateRate description: Update an existing rate. full: true --- mutation Requires `commerce.tax:write`. Update an existing rate. For `SimpleMoneyInput.value`, send `1999` for $19.99 USD, not `19.99`. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `ID!` **required** * `input` `MutationUpdateRateInput!` **required** * `calculationMethod` `RateCalculationMethodEnum` **optional** — The method to be used when applying the rate to a purchase amount. * `createdAt` `DateTime` **optional** — WARNING: DO NOT USE. Deprecated: This field is deprecated and only used for Tax v1 to v2 migration syncs. * `description` `String` **optional** — A human-friendly description. * `jurisdictionId` `ID` **optional** — The ID of the jurisdiction in which this rate applies. * `label` `String` **optional** — A label for display. * `name` `String` **optional** — A unique human-friendly identifier. * `status` `RateStatusEnum` **optional** — The desired status. * `updatedAt` `DateTime` **optional** — WARNING: DO NOT USE. Deprecated: This field is deprecated and only used for Tax v1 to v2 migration syncs. * `value` `RateValueInput` **optional** — The rate's value. * `amount` `SimpleMoneyInput` **optional** — The rate value represented as a fixed money amount. Required if `percentage` is not provided. * `percentage` `String` **optional** — The percentage applied by the rate, out of 100. Required if `amount` is not provided. ## Possible returns * `Rate` `Rate` — An individual tax rate. - `activatedAt` `DateTime` **nullable** — The data & time at which the rate was first activated. - `calculationMethod` `RateCalculationMethodEnum!` **non-null** — The method to be used when applying the rate to a purchase amount. - `classifications` `RateClassificationsConnection` **nullable** — The classifications associated with the rate. - `createdAt` `DateTime!` **non-null** — The data & time at which the rate was created. - `description` `String` **nullable** — The human-friendly description. - `id` `ID!` **non-null** — The globally-unique ID. - `jurisdiction` `Jurisdiction` **nullable** — The jurisdiction in which this rate applies. - `label` `String!` **non-null** — The label for display. - `metafields` `RateMetafieldsConnection` **nullable** - `name` `String!` **non-null** — The unique human-friendly identifier. - `references` `RateReferencesConnection` **nullable** — A reference to the resource in an external service. - `status` `RateStatusEnum!` **non-null** — The current status. - `updatedAt` `DateTime!` **non-null** — The data & time at which the rate was last updated. - `value` `RateValue!` **non-null** — The rate's value # rate (https://developer.godaddy.com/en/docs/references/rest/taxes/rate/queries/rate) --- title: rate description: Get a single rate. full: true --- query Requires `commerce.tax:read`. Get a single rate. `value` is a union. Select `value { __typename ... on RatePercentage { percentage } ... on RateAmount { amount { value currencyCode } } }`. There is no `value { rate }` field. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `id` `ID!` **required** — The rate ID. ## Possible returns * `Rate` `Rate` — An individual tax rate. - `activatedAt` `DateTime` **nullable** — The data & time at which the rate was first activated. - `calculationMethod` `RateCalculationMethodEnum!` **non-null** — The method to be used when applying the rate to a purchase amount. - `classifications` `RateClassificationsConnection` **nullable** — The classifications associated with the rate. - `createdAt` `DateTime!` **non-null** — The data & time at which the rate was created. - `description` `String` **nullable** — The human-friendly description. - `id` `ID!` **non-null** — The globally-unique ID. - `jurisdiction` `Jurisdiction` **nullable** — The jurisdiction in which this rate applies. - `label` `String!` **non-null** — The label for display. - `metafields` `RateMetafieldsConnection` **nullable** - `name` `String!` **non-null** — The unique human-friendly identifier. - `references` `RateReferencesConnection` **nullable** — A reference to the resource in an external service. - `status` `RateStatusEnum!` **non-null** — The current status. - `updatedAt` `DateTime!` **non-null** — The data & time at which the rate was last updated. - `value` `RateValue!` **non-null** — The rate's value # rates (https://developer.godaddy.com/en/docs/references/rest/taxes/rate/queries/rates) --- title: rates description: Get a collection of rates. full: true --- query Requires `commerce.tax:read`. Get a collection of rates. `orderBy` is one key only (`id`, `name`, `createdAt`, or `updatedAt`). Direction must be `ASC` or `DESC`. Sending two keys, or `"desc"`, fails validation. `value` is a union. Select `value { __typename ... on RatePercentage { percentage } ... on RateAmount { amount { value currencyCode } } }`. There is no `value { rate }` field. ## Required headers | Header | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `x-store-id` | Yes | ID of the store the operation targets. Omitting it returns HTTP 200 with a GraphQL error: `extensions.code: "UNAUTHENTICATED"`. | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for credential setup. ## Arguments * `after` `String` **optional** * `before` `String` **optional** * `first` `Int` **optional** * `id` `RateIdFilter` **optional** * `in` `[ID!]` **optional** * `last` `Int` **optional** * `orderBy` `RateOrderBy` **optional** * `createdAt` `OrderByDirectionEnum` **optional** * `id` `OrderByDirectionEnum` **optional** * `name` `OrderByDirectionEnum` **optional** * `updatedAt` `OrderByDirectionEnum` **optional** * `referenceValue` `ReferenceValueFilter` **optional** * `in` `[String!]` **optional** * `status` `RateStatusFilter` **optional** * `eq` `RateStatusEnum` **optional** * `in` `[RateStatusEnum!]` **optional** ## Possible returns * `QueryRatesConnection` `QueryRatesConnection` - `edges` `[QueryRatesConnectionEdge]` **nullable** - `pageInfo` `PageInfo!` **non-null**