{
  "openapi": "3.1.0",
  "info": {
    "title": "DialtoneApp Membership Commerce API",
    "version": "1.0.0",
    "description": "Public commerce discovery and purchase-intent bootstrap API for the DialtoneApp membership offer. This contract publishes the live $9.00 USD/month offer, the DialtoneApp Network Stripe-backed machine-payment path using saved /bot-buyer cards, the optional Nevermined x402 path, and the browser checkout fallback.",
    "termsOfService": "https://dialtoneapp.com/terms",
    "contact": {
      "name": "DialtoneApp",
      "email": "human@dialtoneapp.com",
      "url": "https://dialtoneapp.com/contact"
    }
  },
  "servers": [
    {
      "url": "https://dialtoneapp.com"
    }
  ],
  "tags": [
    {
      "name": "commerce",
      "description": "Membership offer discovery and purchase-intent bootstrap."
    },
    {
      "name": "well-known",
      "description": "Machine-readable commerce discovery documents."
    }
  ],
  "externalDocs": {
    "description": "Public DialtoneApp dogfood article for the membership commerce direction",
    "url": "https://dialtoneapp.com/dogfood"
  },
  "x-dialtoneapp-offer": {
    "offer": "membership-monthly",
    "title": "DialtoneApp Membership",
    "price": {
      "amount": "9.00",
      "currency": "USD",
      "interval": "month"
    }
  },
  "paths": {
    "/.well-known/commerce": {
      "get": {
        "tags": [
          "well-known"
        ],
        "operationId": "getCommerceManifest",
        "summary": "Fetch the DialtoneApp commerce manifest",
        "description": "Returns the machine-readable commerce document for DialtoneApp, including the membership offer, required inputs, supported purchase modes, and discovery URLs.",
        "responses": {
          "200": {
            "description": "Commerce manifest returned.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CommerceManifest"
                }
              }
            }
          }
        }
      }
    },
    "/.well-known/ucp": {
      "get": {
        "tags": [
          "well-known"
        ],
        "operationId": "getUcpManifest",
        "summary": "Fetch the DialtoneApp UCP-style commerce document",
        "description": "Returns a typed commerce discovery companion document for the DialtoneApp membership offer.",
        "responses": {
          "200": {
            "description": "UCP-style document returned.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UcpManifest"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/commerce/membership-offer": {
      "get": {
        "tags": [
          "commerce"
        ],
        "operationId": "getMembershipOffer",
        "summary": "Read the live membership offer",
        "description": "Returns the public DialtoneApp membership offer, the current checkout fallback, and the planned machine-payment paths.",
        "responses": {
          "200": {
            "description": "Membership offer returned.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MembershipOfferResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/commerce/membership-intents": {
      "post": {
        "tags": [
          "commerce"
        ],
        "operationId": "createMembershipIntent",
        "summary": "Bootstrap a membership purchase",
        "description": "Validates the buyer inputs for the DialtoneApp membership offer. When DialtoneApp Network is configured, callers without a payment-signature receive a 402 payment challenge. Callers that retry with a valid DialtoneApp Network payment-signature must also have a saved DialtoneApp Network card from /bot-buyer; successful requests get a Stripe-backed paid membership intent receipt and owner-verification next steps. Optional Nevermined x402 signatures remain supported when configured.",
        "parameters": [
          {
            "name": "payment-signature",
            "in": "header",
            "required": false,
            "description": "DialtoneApp Network signed payment token for an owner with a saved /bot-buyer card, or an optional Nevermined x402 access token when using the Nevermined rail.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MembershipIntentRequest"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Membership intent accepted and next actions returned.",
            "headers": {
              "payment-response": {
                "description": "Base64-encoded payment receipt metadata when the request is accepted through DialtoneApp Network saved-card settlement or Nevermined.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MembershipIntentResponse"
                }
              }
            }
          },
          "400": {
            "description": "The request body is invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "402": {
            "description": "Machine payment is required, the supplied payment-signature is invalid, or the owner has not saved a DialtoneApp Network card.",
            "headers": {
              "payment-required": {
                "description": "Base64-encoded DialtoneApp Network saved-card or Nevermined payment requirement.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentRequiredResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Merchant": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "support_email": {
            "type": [
              "string",
              "null"
            ],
            "format": "email"
          }
        },
        "required": [
          "name",
          "url"
        ],
        "additionalProperties": true
      },
      "Price": {
        "type": "object",
        "properties": {
          "amount": {
            "type": "string"
          },
          "currency": {
            "type": "string"
          },
          "interval": {
            "type": "string"
          }
        },
        "required": [
          "amount",
          "currency",
          "interval"
        ],
        "additionalProperties": false
      },
      "OfferApi": {
        "type": "object",
        "properties": {
          "openapi": {
            "type": "string",
            "format": "uri"
          },
          "offer_lookup": {
            "type": "string",
            "format": "uri"
          },
          "purchase_intent": {
            "type": "string",
            "format": "uri"
          }
        },
        "required": [
          "openapi",
          "offer_lookup",
          "purchase_intent"
        ],
        "additionalProperties": false
      },
      "Offer": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "offer": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "kind": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "price": {
            "$ref": "#/components/schemas/Price"
          },
          "required_inputs": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "optional_inputs": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "purchase_modes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "api": {
            "$ref": "#/components/schemas/OfferApi"
          }
        },
        "required": [
          "id",
          "offer",
          "title",
          "description",
          "kind",
          "status",
          "price",
          "required_inputs",
          "purchase_modes",
          "api"
        ],
        "additionalProperties": false
      },
      "MachinePaymentPath": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "kind": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "label",
          "status",
          "kind"
        ],
        "additionalProperties": false
      },
      "CommerceManifest": {
        "type": "object",
        "properties": {
          "version": {
            "type": "string"
          },
          "merchant": {
            "$ref": "#/components/schemas/Merchant"
          },
          "offers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Offer"
            }
          },
          "auth": {
            "type": "object",
            "additionalProperties": true
          },
          "checkout": {
            "type": "object",
            "additionalProperties": true
          },
          "machine_payment_paths": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MachinePaymentPath"
            }
          },
          "nevermined": {
            "type": "object",
            "additionalProperties": true
          },
          "skyfire": {
            "type": "object",
            "additionalProperties": true
          },
          "discovery": {
            "type": "object",
            "additionalProperties": true
          },
          "legal": {
            "type": "object",
            "additionalProperties": true
          },
          "dialtoneapp_network": {
            "type": "object",
            "additionalProperties": true
          }
        },
        "required": [
          "version",
          "merchant",
          "offers",
          "machine_payment_paths",
          "discovery"
        ],
        "additionalProperties": false
      },
      "UcpManifest": {
        "type": "object",
        "properties": {
          "version": {
            "type": "string"
          },
          "merchant": {
            "$ref": "#/components/schemas/Merchant"
          },
          "offers": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "payment_paths": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MachinePaymentPath"
            }
          },
          "openapi": {
            "type": "string",
            "format": "uri"
          }
        },
        "required": [
          "version",
          "merchant",
          "offers",
          "payment_paths",
          "openapi"
        ],
        "additionalProperties": false
      },
      "MembershipOfferResponse": {
        "type": "object",
        "properties": {
          "merchant": {
            "$ref": "#/components/schemas/Merchant"
          },
          "offer": {
            "$ref": "#/components/schemas/Offer"
          },
          "current_purchase_path": {
            "type": "object",
            "additionalProperties": true
          },
          "planned_machine_payment_paths": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MachinePaymentPath"
            }
          },
          "docs": {
            "type": "object",
            "additionalProperties": true
          }
        },
        "required": [
          "merchant",
          "offer",
          "current_purchase_path",
          "planned_machine_payment_paths",
          "docs"
        ],
        "additionalProperties": false
      },
      "MembershipIntentRequest": {
        "type": "object",
        "properties": {
          "offer": {
            "type": "string",
            "default": "membership-monthly"
          },
          "offer_id": {
            "type": "string",
            "default": "membership-monthly"
          },
          "owner_email": {
            "type": "string",
            "format": "email"
          },
          "website_domain": {
            "type": [
              "string",
              "null"
            ],
            "description": "Optional website domain or URL for attribution. The membership belongs to the account and can cover any domains the user later adds."
          },
          "machine_id": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "owner_email"
        ],
        "additionalProperties": false
      },
      "MembershipIntentResponse": {
        "type": "object",
        "properties": {
          "intent_id": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "merchant": {
            "$ref": "#/components/schemas/Merchant"
          },
          "offer": {
            "$ref": "#/components/schemas/Offer"
          },
          "submitted_inputs": {
            "type": "object",
            "additionalProperties": true
          },
          "verification": {
            "type": "object",
            "additionalProperties": true
          },
          "payment": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": true
          },
          "fulfillment": {
            "type": "object",
            "additionalProperties": true
          },
          "next_actions": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "machine_payment_paths": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MachinePaymentPath"
            }
          },
          "docs": {
            "type": "object",
            "additionalProperties": true
          },
          "note": {
            "type": "string"
          }
        },
        "required": [
          "intent_id",
          "status",
          "merchant",
          "offer",
          "submitted_inputs",
          "verification",
          "payment",
          "fulfillment",
          "next_actions",
          "machine_payment_paths",
          "docs",
          "note"
        ],
        "additionalProperties": false
      },
      "PaymentRequiredResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "provider": {
            "type": "string"
          },
          "payment_required": {
            "type": "object",
            "additionalProperties": true
          },
          "plans": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "docs": {
            "type": "object",
            "additionalProperties": true
          }
        },
        "required": [
          "error",
          "message",
          "provider"
        ],
        "additionalProperties": true
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false
      }
    }
  }
}