{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://goroute.ai/ucp/einvoice.schema.json",
  "name": "ai.goroute.einvoice",
  "title": "E-Invoice Extension",
  "description": "Extends Checkout with the buyer's business identity and Order with the compliant e-invoice or fiscal receipt the merchant issues for it. Version 2026-09-24 (document 1.0.0-draft). Published by GoRoute; anyone may implement it.",
  "$comment": "Composed onto the UCP base schemas with allOf, one $defs entry per parent named in `extends`, as UCP's own extensions do. Field names are shared with the ACP profile of this extension.",
  "$defs": {
    "buyer_business": {
      "title": "Business buyer",
      "description": "The registered business the order is for, supplied by the agent at checkout when its principal buys as a business. Absent, the order is a consumer sale.",
      "type": "object",
      "additionalProperties": false,
      "required": ["legal_name"],
      "anyOf": [{ "required": ["tax_id"] }, { "required": ["peppol_id"] }],
      "properties": {
        "legal_name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 500,
          "description": "The buyer's registered name, as the invoice must show it."
        },
        "tax_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 30,
          "description": "The buyer's tax identifier: a VAT number (EU, with country prefix), ABN (AU), NZBN (NZ), VATIN (OM), or the equivalent. Spaces are ignored."
        },
        "scheme": {
          "type": "string",
          "pattern": "^([A-Za-z]{2}|[0-9]{4})$",
          "description": "What kind of identifier tax_id is: an ISO 3166-1 alpha-2 country code (the country's standard business identifier), or a four-digit Peppol / ISO 6523 ICD scheme code (0208 Belgium enterprise number, 0151 ABN, 0088 GLN, 0242 Oman VATIN ...)."
        },
        "peppol_id": {
          "type": "string",
          "pattern": "^[0-9]{4}:[A-Za-z0-9\\-._]+$",
          "description": "The buyer's Peppol participant identifier as scheme:identifier (for example 0208:0000007720), when the buyer knows it. Takes precedence over tax_id for delivery."
        },
        "order_reference": {
          "type": "string",
          "maxLength": 150,
          "description": "The buyer's own reference for this order (a purchase-order number). Placed on the invoice as the buyer reference (EN 16931 BT-10 / BT-13)."
        },
        "delivery": {
          "type": "string",
          "enum": ["peppol", "email", "none"],
          "default": "peppol",
          "description": "How the buyer wants the document: over the Peppol network to its e-invoicing system, by email as a PDF with the e-invoice embedded, or not at all (the merchant still issues and keeps it; fiscal law is not optional). The merchant may substitute what its country's law allows and says so in einvoice.delivered_via."
        },
        "email": {
          "type": "string",
          "format": "email",
          "description": "Where to send the document when delivery is email, if not the checkout buyer's email."
        }
      }
    },
    "einvoice": {
      "title": "E-invoice",
      "description": "The fiscal document the merchant issued for the order, or why not yet.",
      "type": "object",
      "required": ["status", "document_type", "delivered_via"],
      "properties": {
        "extension": { "type": "string", "const": "ai.goroute.einvoice" },
        "version": { "type": "string", "description": "Version of this extension the object follows, e.g. 1.0.0-draft." },
        "status": {
          "type": "string",
          "enum": ["pending", "issued", "delivered", "failed", "held", "skipped"],
          "description": "pending: not issued yet. issued: issued and, where it is sent, in transit. delivered: the buyer's system acknowledged it. failed: delivery failed (see error). held: the merchant must act before it can be issued (see error). skipped: no fiscal document is required for this order (a consumer sale in a B2B-only mandate)."
        },
        "document_type": {
          "type": "string",
          "enum": ["invoice", "receipt", "credit_note"],
          "description": "invoice: a full (tax) invoice to a business. receipt: a fiscal receipt / simplified tax invoice to a consumer. credit_note: a credit note against an earlier invoice (refund, cancellation)."
        },
        "number": { "type": ["string", "null"], "description": "The document number as issued." },
        "delivered_via": {
          "type": "string",
          "enum": ["peppol", "email", "authority", "none"],
          "description": "peppol: over the Peppol network. email: by email, PDF with the e-invoice embedded. authority: filed with the tax authority only (the buyer is not reachable on the network; a substitute address applies). none: issued and stored, not sent."
        },
        "pdf_url": { "type": ["string", "null"], "format": "uri", "description": "Where the agent can fetch the PDF. May be time-limited." },
        "xml_url": { "type": ["string", "null"], "format": "uri", "description": "Where the agent can fetch the e-invoice XML (UBL, CII). May be time-limited." },
        "network_message_id": { "type": ["string", "null"], "description": "The network's message identifier (Peppol AS4 MessageId) once the document has been handed to the network." },
        "transaction_id": { "type": ["string", "null"], "description": "The issuing provider's transaction identifier." },
        "document_uuid": { "type": ["string", "null"], "description": "The document's UUID where the country's profile assigns one (Oman BTOM-002)." },
        "verify_url": { "type": "string", "format": "uri", "description": "A public verification page for the document, where the country provides one (Oman receipts)." },
        "issued_at": { "type": "string", "format": "date-time" },
        "error": { "type": "string", "description": "In words, when status is failed, held or skipped." }
      }
    },
    "dev.ucp.shopping.checkout": {
      "title": "Checkout with E-Invoice",
      "description": "Checkout extended with the buyer's business identity.",
      "allOf": [
        { "$ref": "https://ucp.dev/2026-08-25/schemas/shopping/checkout.json" },
        {
          "type": "object",
          "properties": {
            "buyer_business": {
              "$ref": "#/$defs/buyer_business",
              "description": "The business the order is for. The agent sets it on create or update; the business echoes it.",
              "ucp_request": { "create": "optional", "update": "optional", "complete": "optional" }
            }
          }
        }
      ]
    },
    "dev.ucp.shopping.order": {
      "title": "Order with E-Invoice",
      "description": "Order extended with the fiscal document issued for it.",
      "allOf": [
        { "$ref": "https://ucp.dev/2026-08-25/schemas/shopping/order.json" },
        {
          "type": "object",
          "properties": {
            "buyer_business": {
              "$ref": "#/$defs/buyer_business",
              "description": "As accepted at checkout.",
              "ucp_request": "omit"
            },
            "einvoice": {
              "$ref": "#/$defs/einvoice",
              "description": "The fiscal document for this order. Present once the business has issued it, or decided it cannot; updated through the order's lifecycle (a credit note follows a refund). A business that declares this capability commits to issuing the document the buyer's country requires after the order completes.",
              "ucp_request": "omit"
            }
          }
        }
      ]
    },
    "platform_schema": {
      "properties": {
        "config": {
          "type": "object",
          "description": "No platform configuration is defined.",
          "additionalProperties": true
        }
      }
    },
    "business_schema": {
      "properties": {
        "config": {
          "type": "object",
          "additionalProperties": true,
          "properties": {
            "documents": {
              "type": "array",
              "items": { "type": "string", "enum": ["invoice", "receipt", "credit_note"] },
              "description": "Which documents this business issues."
            },
            "delivery": {
              "type": "array",
              "items": { "type": "string", "enum": ["peppol", "email", "none"] },
              "description": "Which delivery values this business honours."
            },
            "countries": {
              "type": "array",
              "items": { "type": "string", "pattern": "^[A-Z]{2}$" },
              "description": "Buyer countries the business issues compliant documents for."
            }
          }
        }
      }
    }
  }
}