Everyone

How Domains Work in Commerce

Architecture overview of domain registration, renewal, transfer, and management through Commerce's pluggable registrar module system.

Last updated 1776211200
  • Five Built-In Registrar Modules
  • Domain Statuses
  • Auto-Renew Policy
  • Scheduled Commands
  • Related

    • Overview

    Commerce handles the full domain lifecycle: search, registration, renewal, transfer, lock, WHOIS privacy, and EPP codes. Everything is invoice-driven — clients pay first, then the registrar action fires. No action happens outside of Commerce's billing cycle.

    Architecture

    domain_tlds          domains              domain_contacts
(TLD catalog)    ─▶  (registered)    ─▶  (WHOIS contacts)
(pricing, flags)     (status, expiry)     (registrar contact IDs)
                          │
                          ▼
               DomainRegistrarModule
               (pluggable — one active at a time)
                          │
                          ▼
                    Registrar API

    Key Database Tables

    Table Purpose
    domain_tlds TLD catalog with pricing, min/max years, EPP/privacy flags
    domains One record per registered or transferred domain
    domain_contacts WHOIS contact details + registrar-side contact ID cache

    Five Built-In Registrar Modules

    Module Registrar API Style
    resellerclub ResellerClub (LogicBoxes) HTTPS GET + JSON
    enom Enom (Tucows) HTTPS GET + XML
    opensrs OpenSRS (Tucows) HTTPS POST + OPS XML
    namecheap Namecheap HTTPS GET + XML
    centralnic CentralNic Reseller (Hexonet) HTTPS POST + key=value

    Only one registrar is active at a time. New domains always use the active module. Custom modules can be added by implementing DomainRegistrarModule.

    Domain Statuses

    Status Meaning
    pending Registration/transfer in progress
    active Live and registered
    expired Past expiry date, not yet deleted
    transferred_away Client moved domain to another registrar
    cancelled Cancelled before completion
    fraud Flagged as fraudulent order
    redemption In registrar redemption grace period

    Auto-Renew Policy

    Commerce keeps auto-renew OFF at the registrar level for all domains. This ensures all renewals are controlled by Commerce invoices rather than silently charged at the registrar. The renewal flow is:

    1. commerce:check-expiring-domains (daily 04:00) generates renewal invoices 30 days before expiry.
    2. Client pays the invoice.
    3. RenewDomainJob fires → registrar renews → expiry_date updated.

    If the invoice goes unpaid, the domain expires at the registrar. The commerce:sync-domain-statuses job (daily 05:00) detects this and updates the domain's status.

    Scheduled Commands

    Command Schedule Purpose
    commerce:check-expiring-domains Daily 04:00 Generate renewal invoices 30 days before expiry
    commerce:sync-domain-statuses Daily 05:00 Sync active/expired status with registrar API

    Related

    Next
    TLD Manager →