Just Domain Buy Domain API

openapi: 3.2.0
info:
  title: just-domain-mcp Buy Domain API
  version: 0.1.0
tags:
- name: Buy Domain
paths:
  /api/buy-domain:
    post:
      summary: Post Buy Domain
      operationId: post_buy_domain_api_buy_domain_post
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Idempotency-Key
      - name: Authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BuyDomainRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuyDomainResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Buy Domain
components:
  schemas:
    OrderAttribution:
      properties:
        utm_source:
          anyOf:
          - type: string
          - type: 'null'
          title: Utm Source
        utm_medium:
          anyOf:
          - type: string
          - type: 'null'
          title: Utm Medium
        utm_campaign:
          anyOf:
          - type: string
          - type: 'null'
          title: Utm Campaign
        utm_content:
          anyOf:
          - type: string
          - type: 'null'
          title: Utm Content
        utm_term:
          anyOf:
          - type: string
          - type: 'null'
          title: Utm Term
      type: object
      title: OrderAttribution
      description: 'Where the paying click came from: the utm_* values the landing URL carried.


        The website reads them off the ad or campaign link and sends them with

        the purchase so they land on the order row (JD1 in the Just Domain

        metrics ledger). Every key is optional and every value is cleaned by

        `clean_attribution_value`; keys this model does not name are ignored.'
    BuyDomainRequest:
      properties:
        domain:
          $ref: '#/components/schemas/DomainSpec'
        registrant:
          $ref: '#/components/schemas/RegistrantInfo'
        expected_price_usd:
          anyOf:
          - type: number
          - type: 'null'
          title: Expected Price Usd
          description: Price ceiling the client computed. If the server's resolved price exceeds this, the call returns 409 price_higher_than_expected so the client can re-confirm with the user.
        auto_renew:
          anyOf:
          - $ref: '#/components/schemas/AutoRenewConsentPayload'
          - type: 'null'
          description: Auto-renew choice + the disclosure that was shown. Omitted by clients that predate the control; the order is then created with auto-renew OFF and no consent row. We never infer consent from silence - a missing payload is a customer who was shown nothing, and nothing is exactly what we may charge them.
        attribution:
          anyOf:
          - $ref: '#/components/schemas/OrderAttribution'
          - type: 'null'
          description: The utm_* values of the link the buyer arrived on, recorded on the order. Optional; a value that is not a short printable ASCII string is dropped, and a malformed object is ignored, so this field can never refuse a purchase.
      type: object
      required:
      - domain
      - registrant
      title: BuyDomainRequest
    BuyDomainResponse:
      properties:
        order_id:
          type: string
          title: Order Id
        status:
          type: string
          title: Status
        amount_minor:
          type: integer
          title: Amount Minor
        currency:
          type: string
          title: Currency
        client_secret:
          type: string
          title: Client Secret
        payment_intent_id:
          type: string
          title: Payment Intent Id
      type: object
      required:
      - order_id
      - status
      - amount_minor
      - currency
      - client_secret
      - payment_intent_id
      title: BuyDomainResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    DomainSpec:
      properties:
        sld:
          type: string
          title: Sld
          description: Second-level domain, e.g. 'myname'.
        tld:
          type: string
          title: Tld
          description: TLD without leading dot, e.g. 'com'.
        years:
          type: integer
          maximum: 10.0
          minimum: 1.0
          title: Years
          default: 1
      type: object
      required:
      - sld
      - tld
      title: DomainSpec
    RegistrantInfo:
      properties:
        first_name:
          type: string
          title: First Name
        last_name:
          type: string
          title: Last Name
        org_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Org Name
        email:
          type: string
          title: Email
        phone:
          type: string
          title: Phone
        country:
          type: string
          title: Country
        address1:
          type: string
          title: Address1
        city:
          type: string
          title: City
        state:
          type: string
          title: State
        postal_code:
          type: string
          title: Postal Code
        additional_data:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Additional Data
          description: 'Extra registrant data a registry demands beyond standard contacts - a .us nexus declaration, an ISOC-IL registrant ID. Keyed by OUR checkout form keys (`us_nexus_category`, `registrant_id`), NOT by a registrar''s wire field names: the translation happens in the provider adapter, so a registrar swap does not rewrite the checkout form. Validated against the ending''s JSON Schema BEFORE a card is charged - see `shared.services.requirements`.'
      type: object
      required:
      - first_name
      - last_name
      - email
      - phone
      - country
      - address1
      - city
      - state
      - postal_code
      title: RegistrantInfo
      description: 'WHOIS registrant contact, persisted alongside an `Order`.


        Internal DTO. The HTTP API (`/api/buy-domain`) accepts and validates

        these fields; the Openprovider registration job reads them off the

        Order row when fulfilling.'
    AutoRenewConsentPayload:
      properties:
        enabled:
          type: boolean
          title: Enabled
          description: The state of the auto-renew control when the user paid.
        disclosure_version:
          type: string
          maxLength: 32
          title: Disclosure Version
          description: Which disclosure template produced the text below.
        disclosure_text:
          type: string
          maxLength: 4000
          title: Disclosure Text
          description: The automatic-renewal offer terms exactly as rendered.
      type: object
      required:
      - enabled
      - disclosure_version
      - disclosure_text
      title: AutoRenewConsentPayload
      description: 'What the checkout showed about auto-renewal, and what the user chose.


        California BPC §17602(a)(4) makes express affirmative consent **to the

        renewal terms** a duty distinct from consent to the agreement containing

        them, and §17602(a)(6) requires the verification of that consent to be

        retained. So the client sends the exact text it rendered, not a flag: a

        row that says "they agreed" without saying "to what" is not evidence.


        `disclosure_text` is a client assertion - the same object drives the

        render and this payload, so they cannot drift within a release, but the

        server did not witness the pixels. Named as a limitation rather than

        dressed up as proof.'