openapi: 3.1.0
info:
  title: Web3 Partner API v3 account Cart API
  version: 3.0.0
  contact:
    name: Unstoppable Domains (Partner Engineering)
    email: partnerengineering@unstoppabledomains.com
  description: "# Feature Overview\nThe Web3 Partner API v3 provides you with the ability to lookup, register and manage Web3 domains. The API exposes a RESTful interface for interacting with Web3 domains and the Unstoppable Domains registry.\n- Lookup Domains: Search for specific domains or find suggested alternatives, to determine pricing, availability and on-chain details\n- Registering Domains: Secure domains into your dedicated Custody wallets to maintain the domains on the blockchain\n- Manage Domains: Update records on the blockchain or transfer the domain to external owners, all through a simple API interface\n\n## Custody Solution\nThe API takes the hassle of Web3 out of the equation. Unstoppable Domains will handle all blockchain interactions and concepts, while Partners simply use a RESTful API for managing domains.\n\nSince the domains will be in custody of the Partner, through Unstoppable Domains, the Partner is empowered to make any and all changes to the domains on behalf of their users.\n\nUnder the hood, Unstoppable Domains will manage dedicated custodial wallets for Partner-owned domains. These wallets are not shared between Partners and will uniquely identify the Partner on the various supported blockchains.\n\nShould the need arise to remove domains from custody, this is supported by changing the owner of domains to external owners.\n\n## Payments\nThe API will keep track of a running balance of charges and Unstoppable Domains will periodically invoice Partners to settle that balance. This empowers Partners to build payment processing in a way that works best for them.\n\n\n## Blockchain Support\nDomain details can be viewed across all of our supported blockchains:\n- Ethereum (ETH)\n- Polygon PoS (MATIC)\n- Base (BASE)\n\nDomains can **only be managed on Polygon PoS (MATIC) and Base (BASE)**. Domains on Ethereum (ETH) are readonly, but management support is coming soon.\n\n# Important Concepts\nThe API has some important concepts, in addition to Web3 Domains, that provide added utility, consistency and information.\n\n## Domain Ownership Type\nWeb3 domains exist on the supported Blockchains, and are owned by wallet addresses associated with those Blockchains. \nWe take ownership a step further, to provide improved security and reliability, by including an owner `type` in our ownership data.\nThe result is that a Domain's owner is defined by two values: `address` and `type`\n\nThe owner `type` can be one of the following:\n- `NONE`: Either the domain has never been owned or belongs to a \"burn\" address\n- `UD`: Owned by Unstoppable Domains\n- `SELF`: Domain belongs to a wallet addressed associated with your account, indicating you are able to manage it via the API\n- `EXTERNAL`: Owner doesn't qualify as any of the above. Changing to an `EXTERNAL` owner will result in the domain belonging to an address outside of the management of Unstoppable Domains and we will have no way to recover it.\n\nBy defining an owner in two parts (`address` and `type`) we ensure any irreversible action, such as transferring ownership, is deliberate and intended by requiring both the `address` and `type` in the request.\n\n## Operations\nAll interactions with the API that initiate changes will create an Operation for tracking that change.\nOperations can complete immediately or run in the background over the course of several minutes, depending on the Operation type and current conditions on the Blockchain.\n\nOperations include dependencies that represent the smaller units of work associated with the overall operation. These dependencies can also be tracked through the API and each have their own status and metadata.\n\nYour integration should properly handle and anticipate all of the following possible statuses for Operations and their dependencies:\n- `QUEUED` : The Operation has not started processing yet, but should be started shortly\n- `PROCESSING` : The Operation has started, often involving sending transactions to the Blockchain\n- `SIGNATURE_REQUIRED`: The operation is awaiting a signature in order to continue processing. This is only relevant to Self-Custody domain management.\n- `COMPLETED` : The Operation has finished processing successfully\n- `FAILED` : The Operation has finished processing and has either fully or partially failed\n- `CANCELLED` : The Operation has been cancelled, usually due to a failure with a sibling dependency\n\nSee the [Operations](/openapi/partner/v3/#tag/operations) API for additional information.\n\n## Wallets\nDomains ownership on the Blockchain is handled by associating a Domain with an \"address\". These addresses are typically managed by Wallets (usually in the form of an application on your computer or mobile device) that manage the private key for the public \"address\".\n\nThe API provides endpoints for creating/managing Wallets within your account to enable you to handle Domain ownership distribution in whatever way works for you. Any Domain that is owned by one of your account's Wallets is fully in your control to manage.\n\nSee the [Wallets](/openapi/partner/v3/#tag/wallets) API for additional information.\n\n# Get Access\nSee our quickstart guide for getting your Partner API key: [Set up Partner API Access](https://docs.unstoppabledomains.com/domain-distribution-and-management/quickstart/retrieve-an-api-key/)\n\nIf you have any questions, contact our [Partner Engineering Team](mailto:partnerengineering@unstoppabledomains.com?subject=Partner%20API%20v3%20Inquiry) to help with API access or learn more.\n"
servers:
- url: https://api.unstoppabledomains.com/partner/v3
  description: Production
- url: https://api.ud-sandbox.com/partner/v3
  description: Sandbox
security:
- bearer: []
tags:
- name: Cart
  description: Shopping cart management, payment methods, and checkout (requires authentication)
paths:
  /mcp/v1/actions/ud_cart_get:
    post:
      operationId: cartGet
      summary: Get shopping cart with pricing
      description: Get the current shopping cart contents with comprehensive pricing breakdown including discounts, taxes, and credits. Optionally apply a discount code. Requires authentication.
      tags:
      - Cart
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                discountCode:
                  type: string
                  description: Optional discount/promo code to apply
      responses:
        '200':
          description: Cart contents with pricing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CartResponse'
        '401':
          description: Authentication required
  /mcp/v1/actions/ud_cart_add_domain_registration:
    post:
      operationId: cartAddDomainRegistration
      summary: Add domains to cart for registration
      description: Add one or more domains to the shopping cart for fresh registration. Returns the updated cart summary. Requires authentication.
      tags:
      - Cart
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - domains
              properties:
                domains:
                  type: array
                  items:
                    type: object
                    required:
                    - name
                    properties:
                      name:
                        type: string
                        description: Full domain name (e.g., "example.com")
                      productType:
                        type: string
                        description: 'Product type (default: Domain)'
                      quantity:
                        type: integer
                        description: 'Registration years (1-10, default: 1)'
                        minimum: 1
                        maximum: 10
                  minItems: 1
                  description: Array of domains to add to the cart
      responses:
        '200':
          description: Updated cart
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddToCartResponse'
        '401':
          description: Authentication required
  /mcp/v1/actions/ud_cart_add_domain_listed:
    post:
      operationId: cartAddDomainListed
      summary: Add marketplace-listed domains to cart
      description: Add one or more marketplace-listed domains to the shopping cart. Supports both "Buy it now" (full price) and "Lease to Own" (monthly payments) purchases. Requires authentication.
      tags:
      - Cart
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - domains
              properties:
                domains:
                  type: array
                  items:
                    type: object
                    required:
                    - name
                    properties:
                      name:
                        type: string
                        description: Full domain name listed on marketplace (e.g., "premium.com")
                      leaseToOwnOptions:
                        type: object
                        description: Optional lease-to-own options. Omit for immediate "Buy it now" purchase.
                        properties:
                          type:
                            type: string
                            enum:
                            - equal_installments
                            - down_payment_plus_equal_installments
                            description: 'Payment type: "equal_installments" or "down_payment_plus_equal_installments"'
                          termLength:
                            type: integer
                            minimum: 2
                            maximum: 120
                            description: Number of monthly payments (2-120)
                          downPaymentPercentage:
                            type: number
                            minimum: 10
                            maximum: 90
                            description: Down payment percentage (10-90%), required for down_payment type
                  minItems: 1
                  maxItems: 50
                  description: Array of marketplace-listed domains to add to cart
      responses:
        '200':
          description: Updated cart with listed domains
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddListedDomainToCartResponse'
        '401':
          description: Authentication required
  /mcp/v1/actions/ud_cart_add_domain_afternic:
    post:
      operationId: cartAddDomainAfternic
      summary: Add Afternic marketplace domains to cart
      description: Add one or more Afternic marketplace domains to the shopping cart. For domains with marketplace.source = "afternic" and marketplace.status = "registered-listed-for-sale" from search results. Requires authentication.
      tags:
      - Cart
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - domains
              properties:
                domains:
                  type: array
                  items:
                    type: object
                    required:
                    - name
                    properties:
                      name:
                        type: string
                        description: Full domain name from Afternic marketplace (e.g., "premium.com")
                  minItems: 1
                  maxItems: 50
                  description: Array of Afternic marketplace domains to add to cart
      responses:
        '200':
          description: Updated cart with Afternic domains
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddAfternicDomainToCartResponse'
        '401':
          description: Authentication required
  /mcp/v1/actions/ud_cart_add_domain_sedo:
    post:
      operationId: cartAddDomainSedo
      summary: Add Sedo marketplace domains to cart
      description: Add one or more Sedo marketplace domains to the shopping cart. For domains with marketplace.source = "sedo" and marketplace.status = "registered-listed-for-sale" from search results. Requires authentication.
      tags:
      - Cart
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - domains
              properties:
                domains:
                  type: array
                  items:
                    type: object
                    required:
                    - name
                    properties:
                      name:
                        type: string
                        description: Full domain name from Sedo marketplace (e.g., "premium.com")
                  minItems: 1
                  maxItems: 50
                  description: Array of Sedo marketplace domains to add to cart
      responses:
        '200':
          description: Updated cart with Sedo domains
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddSedoDomainToCartResponse'
        '401':
          description: Authentication required
  /mcp/v1/actions/ud_cart_add_domain_renewal:
    post:
      operationId: cartAddDomainRenewal
      summary: Add domain renewals to cart
      description: Add one or more domain renewals to the shopping cart. User must own the domains to renew them. Returns the updated cart summary. Requires authentication.
      tags:
      - Cart
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - domains
              properties:
                domains:
                  type: array
                  items:
                    type: object
                    required:
                    - name
                    properties:
                      name:
                        type: string
                        description: Full domain name to renew (e.g., "example.com")
                      quantity:
                        type: integer
                        description: 'Renewal period in years (1-10, default: 1)'
                        minimum: 1
                        maximum: 10
                  minItems: 1
                  maxItems: 50
                  description: Array of domains to add renewal to cart
      responses:
        '200':
          description: Updated cart with renewals
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddDomainRenewalToCartResponse'
        '401':
          description: Authentication required
  /mcp/v1/actions/ud_cart_remove:
    post:
      operationId: cartRemove
      summary: Remove items from cart
      description: Remove one or more items from the shopping cart by product ID. Returns the updated cart. Requires authentication.
      tags:
      - Cart
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - productIds
              properties:
                productIds:
                  type: array
                  items:
                    type: number
                  minItems: 1
                  description: Array of product IDs to remove from the cart
      responses:
        '200':
          description: Updated cart
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RemoveFromCartResponse'
        '401':
          description: Authentication required
  /mcp/v1/actions/ud_cart_get_payment_methods:
    post:
      operationId: cartGetPaymentMethods
      summary: Get available payment methods
      description: Get saved credit cards, account balance, and promo credits available for checkout. Requires authentication.
      tags:
      - Cart
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties: {}
      responses:
        '200':
          description: Payment methods
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentMethodsResponse'
        '401':
          description: Authentication required
  /mcp/v1/actions/ud_cart_add_payment_method_url:
    post:
      operationId: cartAddPaymentMethodUrl
      summary: Get URL to add a payment method
      description: Get a URL to the payment management page where users can securely add a new credit card. Requires authentication.
      tags:
      - Cart
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties: {}
      responses:
        '200':
          description: Add payment method URL
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddPaymentMethodUrlResponse'
        '401':
          description: Authentication required
  /mcp/v1/actions/ud_cart_checkout:
    post:
      operationId: cartCheckout
      summary: Complete cart checkout
      description: Complete checkout for cart items using saved payment method or account balance. Requires authentication.
      tags:
      - Cart
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                paymentMethodId:
                  type: string
                  description: Stripe payment method ID for card payment. Required if cart total exceeds account balance.
                useAccountBalance:
                  type: boolean
                  description: Whether to apply account balance to reduce total. Defaults to true.
                discountCode:
                  type: string
                  description: Optional discount/promo code to apply
                contactId:
                  type: string
                  description: ICANN contact ID for DNS domain registration. Get IDs from ud_contacts_list. If not specified, uses the most recent contact.
      responses:
        '200':
          description: Checkout result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckoutResponse'
        '401':
          description: Authentication required
  /mcp/v1/actions/ud_cart_get_url:
    post:
      operationId: cartGetUrl
      summary: Get checkout URL
      description: Generate a checkout URL for completing the purchase in a browser. Returns the URL along with a cart summary. Requires authentication.
      tags:
      - Cart
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                discountCode:
                  type: string
                  description: Optional discount/promo code to include in checkout URL
      responses:
        '200':
          description: Checkout URL and cart summary
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckoutUrlResponse'
        '401':
          description: Authentication required
components:
  schemas:
    CartResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/CartItem'
        itemCount:
          type: number
        pricing:
          type: object
          properties:
            totalOrderValue:
              type: number
            totalOrderValueFormatted:
              type: string
            preTaxAmountDue:
              type: number
            preTaxAmountDueFormatted:
              type: string
            salesTax:
              type: number
            salesTaxFormatted:
              type: string
            taxRate:
              type: number
            promoCreditsUsed:
              type: number
            promoCreditsUsedFormatted:
              type: string
            storeCreditsUsed:
              type: number
            storeCreditsUsedFormatted:
              type: string
            accountBalanceUsed:
              type: number
            accountBalanceUsedFormatted:
              type: string
            totalAmountDue:
              type: number
            totalAmountDueFormatted:
              type: string
        discounts:
          type: array
          items:
            type: object
            properties:
              amount:
                type: number
              amountFormatted:
                type: string
              type:
                type: string
              title:
                type: string
              code:
                type:
                - string
                - 'null'
              productIds:
                type: array
                items:
                  type: number
        totalDiscounts:
          type: number
        totalDiscountsFormatted:
          type: string
    RemoveFromCartResponse:
      type: object
      properties:
        removedProductIds:
          type: array
          items:
            type: number
        removedCount:
          type: number
        cart:
          type: object
          properties:
            itemCount:
              type: number
            subtotal:
              type: number
            subtotalFormatted:
              type: string
            items:
              type: array
              items:
                $ref: '#/components/schemas/CartItem'
    CheckoutResponse:
      type: object
      properties:
        success:
          type: boolean
        orderId:
          type: number
        paymentId:
          type: number
        summary:
          type: object
          properties:
            itemCount:
              type: number
            domains:
              type: array
              items:
                type: string
            subtotal:
              type: number
            subtotalFormatted:
              type: string
            discounts:
              type: number
            discountsFormatted:
              type: string
            creditsUsed:
              type: number
            creditsUsedFormatted:
              type: string
            salesTax:
              type: number
            salesTaxFormatted:
              type: string
            totalCharged:
              type: number
            totalChargedFormatted:
              type: string
            paymentMethod:
              type: string
        note:
          type: string
          description: Optional note about contact selection when user has multiple contacts
    AddAfternicDomainToCartResponse:
      type: object
      description: Response for adding Afternic marketplace domains to cart
      properties:
        addedProducts:
          type: array
          items:
            type: object
            properties:
              domain:
                type: string
                description: Domain name
              success:
                type: boolean
              productId:
                type: number
              price:
                type: string
                description: Formatted price when available
              error:
                type: string
        successCount:
          type: number
        failureCount:
          type: number
        cart:
          type: object
          properties:
            itemCount:
              type: number
            subtotal:
              type: number
            subtotalFormatted:
              type: string
    AddDomainRenewalToCartResponse:
      type: object
      description: Response for adding domain renewals to cart
      properties:
        addedRenewals:
          type: array
          items:
            type: object
            properties:
              domain:
                type: string
                description: Domain name
              success:
                type: boolean
              productId:
                type: number
              renewalPeriodYears:
                type: number
                description: Renewal period in years
              error:
                type: string
        successCount:
          type: number
        failureCount:
          type: number
        cart:
          type: object
          properties:
            itemCount:
              type: number
            subtotal:
              type: number
            subtotalFormatted:
              type: string
    AddListedDomainToCartResponse:
      type: object
      description: Response for adding marketplace-listed domains to cart
      properties:
        addedProducts:
          type: array
          items:
            type: object
            properties:
              domain:
                type: string
                description: Domain name
              success:
                type: boolean
              productId:
                type: number
              purchaseType:
                type: string
                enum:
                - buy_now
                - lease_to_own
                description: Type of purchase
              listingPrice:
                type: string
                description: Formatted listing price
              monthlyPayment:
                type: string
                description: Formatted monthly payment (for LTO only)
              termLength:
                type: number
                description: Number of months (for LTO only)
              error:
                type: string
        successCount:
          type: number
        failureCount:
          type: number
        cart:
          type: object
          properties:
            itemCount:
              type: number
            subtotal:
              type: number
            subtotalFormatted:
              type: string
    CartItem:
      type: object
      properties:
        productId:
          type: number
        productCode:
          type: string
        productType:
          type: string
        domain:
          type:
          - string
          - 'null'
        originalPrice:
          type: number
        originalPriceFormatted:
          type: string
        discountAmount:
          type: number
        discountAmountFormatted:
          type: string
        promoCreditsApplied:
          type: number
        accountBalanceApplied:
          type: number
        salesTax:
          type: number
        fees:
          type: array
          items:
            type: object
    AddPaymentMethodUrlResponse:
      type: object
      properties:
        url:
          type: string
          description: Authenticated magic link URL to the payment management page (single-use, valid for 60 seconds)
        expiresIn:
          type: number
          description: Seconds until the magic link expires (URL is single-use)
        instructions:
          type: string
          description: Guidance for the user on how to add a card
    AddToCartResponse:
      type: object
      properties:
        addedProducts:
          type: array
          items:
            type: object
            properties:
              domain:
                type: string
              success:
                type: boolean
              error:
                type: string
              productId:
                type: number
        successCount:
          type: number
        failureCount:
          type: number
        cart:
          type: object
          properties:
            itemCount:
              type: number
            subtotal:
              type: number
            subtotalFormatted:
              type: string
    AddSedoDomainToCartResponse:
      type: object
      description: Response for adding Sedo marketplace domains to cart
      properties:
        addedProducts:
          type: array
          items:
            type: object
            properties:
              domain:
                type: string
                description: Domain name
              success:
                type: boolean
              productId:
                type: number
              price:
                type: string
                description: Formatted price when available
              error:
                type: string
        successCount:
          type: number
        failureCount:
          type: number
        cart:
          type: object
          properties:
            itemCount:
              type: number
            subtotal:
              type: number
            subtotalFormatted:
              type: string
    CheckoutUrlResponse:
      type: object
      properties:
        checkoutUrl:
          type: string
        expiresIn:
          type: number
          description: Seconds until the magic link expires (URL is single-use)
        cartSummary:
          type: object
          properties:
            itemCount:
              type: number
            subtotal:
              type: number
            subtotalFormatted:
              type: string
            items:
              type: array
              items:
                type: object
        discountCode:
          type:
          - string
          - 'null'
        instructions:
          type: string
    PaymentMethodsResponse:
      type: object
      properties:
        savedCards:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: Payment method ID
              brand:
                type: string
                description: Card brand
              last4:
                type: string
                description: Last 4 digits
              expMonth:
                type: number
              expYear:
                type: number
              isExpired:
                type: boolean
              isDefault:
                type: boolean
        accountBalance:
          type: object
          properties:
            amount:
              type: number
              description: Balance in cents
            amountFormatted:
              type: string
        promoCredits:
          type: object
          properties:
            amount:
              type: number
              description: Promo credits in cents
            amountFormatted:
              type: string
        summary:
          type: object
          properties:
            hasValidCards:
              type: boolean
            validCardCount:
              type: number
            hasAccountBalance:
              type: boolean
            hasPromoCredits:
              type: boolean
            totalCredits:
              type: number
              description: Combined account balance + promo credits
            totalCreditsFormatted:
              type: string
            canCheckout:
              type: boolean
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT