Unstoppable Domains Cart API

openapi: 3.2.0
info:
  title: User Cart API
  description: 'Search, check availability, and purchase traditional DNS domains. This API enables AI assistants to help users find and buy domain names.


    When using the API directly, you will need an API key. See [API Key setup](/user-api/overview#api-key-advanced) for instructions.'
  version: 1.0.0
  contact:
    name: Unstoppable Domains
    url: https://unstoppabledomains.com
    email: support@unstoppabledomains.com
  x-logo:
    url: https://unstoppabledomains.com/images/logos/ud-logo-icon.svg
servers:
- url: https://api.unstoppabledomains.com
  description: Production server
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:
    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
    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
    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
    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
    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
    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
    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
    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'
    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
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key for authenticated operations. Obtain from your Unstoppable Domains account settings.