{
  "openapi": "3.1.0",
  "info": {
    "title": "AI Content Drop scoped billing API",
    "version": "2026-09-13.v1",
    "description": "Human-invoked CLI/SDK billing contract. Excluded from product MCP resources and plugin manifests. New writes are sandbox-only and require server configuration. Owned subscription and history reads expose persisted records, environment and incomplete legacy history; unavailable storage returns 503. Reconciliation and commercial management remain unavailable. X-Sandbox is a generation flag and does not simulate billing. No checkout URL or browser return grants entitlement."
  },
  "servers": [
    {
      "url": "https://aicontentdrop.com"
    }
  ],
  "tags": [
    {
      "name": "billing",
      "description": "Explicitly scoped, owned financial operations"
    }
  ],
  "paths": {
    "/v1/billing/catalog": {
      "get": {
        "operationId": "billingCatalog",
        "tags": [
          "billing"
        ],
        "summary": "Read the versioned server catalog",
        "security": [],
        "responses": {
          "200": {
            "description": "Successful result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Catalog"
                }
              }
            }
          },
          "401": {
            "description": "Missing API key"
          },
          "403": {
            "description": "Explicit billing scope missing; OAuth and catalog registration tokens cannot authorize billing"
          },
          "503": {
            "description": "Configuration, accepted projections or sandbox validation unavailable. No historical-provider fallback."
          }
        }
      }
    },
    "/v1/billing/checkouts": {
      "post": {
        "operationId": "createBillingCheckout",
        "tags": [
          "billing"
        ],
        "summary": "Create a hosted human checkout handoff",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "x-required-scope": "billing:checkout",
        "responses": {
          "200": {
            "description": "Successful result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Checkout"
                }
              }
            }
          },
          "401": {
            "description": "Missing API key"
          },
          "403": {
            "description": "Explicit billing scope missing; OAuth and catalog registration tokens cannot authorize billing"
          },
          "503": {
            "description": "Configuration, accepted projections or sandbox validation unavailable. No historical-provider fallback."
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CheckoutRequest"
              }
            }
          }
        }
      }
    },
    "/v1/billing/checkouts/{checkoutId}": {
      "get": {
        "operationId": "billingCheckout",
        "tags": [
          "billing"
        ],
        "summary": "Read an owned checkout status",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "x-required-scope": "billing:read",
        "responses": {
          "200": {
            "description": "Successful result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CheckoutStatus"
                }
              }
            }
          },
          "401": {
            "description": "Missing API key"
          },
          "403": {
            "description": "Explicit billing scope missing; OAuth and catalog registration tokens cannot authorize billing"
          },
          "503": {
            "description": "Configuration, accepted projections or sandbox validation unavailable. No historical-provider fallback."
          }
        },
        "parameters": [
          {
            "name": "checkoutId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ]
      }
    },
    "/v1/billing/subscription": {
      "get": {
        "operationId": "billingStatus",
        "tags": [
          "billing"
        ],
        "summary": "Read the canonical owned subscription",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "x-required-scope": "billing:read",
        "responses": {
          "200": {
            "description": "Successful result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "subscription"
                  ],
                  "properties": {
                    "subscription": {
                      "type": [
                        "object",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing API key"
          },
          "403": {
            "description": "Explicit billing scope missing; OAuth and catalog registration tokens cannot authorize billing"
          },
          "503": {
            "description": "Configuration, accepted projections or sandbox validation unavailable. No historical-provider fallback."
          }
        }
      }
    },
    "/v1/billing/history": {
      "get": {
        "operationId": "billingHistory",
        "tags": [
          "billing"
        ],
        "summary": "Read owned historical payments",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "x-required-scope": "billing:read",
        "responses": {
          "200": {
            "description": "Successful result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/History"
                }
              }
            }
          },
          "401": {
            "description": "Missing API key"
          },
          "403": {
            "description": "Explicit billing scope missing; OAuth and catalog registration tokens cannot authorize billing"
          },
          "503": {
            "description": "Configuration, accepted projections or sandbox validation unavailable. No historical-provider fallback."
          }
        },
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 256
            }
          }
        ]
      }
    },
    "/v1/billing/portal-sessions": {
      "post": {
        "operationId": "createBillingPortal",
        "tags": [
          "billing"
        ],
        "summary": "Create a short-lived owned management handoff",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "x-required-scope": "billing:manage",
        "responses": {
          "200": {
            "description": "Successful result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "url"
                  ],
                  "properties": {
                    "url": {
                      "type": "string",
                      "format": "uri"
                    },
                    "expiresAt": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing API key"
          },
          "403": {
            "description": "Explicit billing scope missing; OAuth and catalog registration tokens cannot authorize billing"
          },
          "503": {
            "description": "Configuration, accepted projections or sandbox validation unavailable. No historical-provider fallback."
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "idempotencyKey",
                  "returnTarget"
                ],
                "properties": {
                  "idempotencyKey": {
                    "type": "string",
                    "minLength": 16,
                    "maxLength": 128,
                    "pattern": "^[A-Za-z0-9_-]+$"
                  },
                  "returnTarget": {
                    "enum": [
                      "billing",
                      "generate"
                    ]
                  }
                },
                "additionalProperties": false
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "acd_live_",
        "description": "User-created key with individually selected billing permissions. Existing read/generate scopes never imply financial access."
      }
    },
    "schemas": {
      "Catalog": {
        "type": "object",
        "required": [
          "version",
          "currency",
          "enabled",
          "reason",
          "items"
        ],
        "properties": {
          "version": {
            "type": "string"
          },
          "currency": {
            "type": "string"
          },
          "enabled": {
            "type": "boolean"
          },
          "reason": {
            "type": [
              "string",
              "null"
            ]
          },
          "items": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "skuId",
                "kind",
                "name",
                "amountMinor",
                "currency",
                "credits",
                "availability"
              ],
              "properties": {
                "skuId": {
                  "type": "string"
                },
                "kind": {
                  "enum": [
                    "subscription",
                    "topup",
                    "quiz"
                  ]
                },
                "name": {
                  "type": "string"
                },
                "amountMinor": {
                  "type": "integer"
                },
                "currency": {
                  "type": "string"
                },
                "credits": {
                  "type": "integer"
                },
                "availability": {
                  "type": "object",
                  "required": [
                    "enabled",
                    "reason"
                  ],
                  "properties": {
                    "enabled": {
                      "type": "boolean"
                    },
                    "reason": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      },
      "CheckoutRequest": {
        "oneOf": [
          {
            "type": "object",
            "required": [
              "kind",
              "skuId",
              "catalogVersion",
              "idempotencyKey",
              "returnTarget"
            ],
            "properties": {
              "kind": {
                "const": "subscription"
              },
              "skuId": {
                "type": "string",
                "pattern": "^subscription:(starter|professional|ultra|enterprise_max):s[012]:(monthly|annual)$"
              },
              "catalogVersion": {
                "type": "string",
                "minLength": 1,
                "maxLength": 80
              },
              "idempotencyKey": {
                "type": "string",
                "minLength": 16,
                "maxLength": 128,
                "pattern": "^[A-Za-z0-9_-]+$"
              },
              "returnTarget": {
                "enum": [
                  "billing",
                  "generate",
                  "quiz"
                ]
              },
              "offerId": {
                "enum": [
                  "seedance-starter-first-month-v1",
                  "launch-personal-v1",
                  "launch-extra-v1",
                  "recovery-v1"
                ]
              }
            },
            "additionalProperties": false
          },
          {
            "type": "object",
            "required": [
              "kind",
              "skuId",
              "catalogVersion",
              "idempotencyKey",
              "returnTarget"
            ],
            "properties": {
              "kind": {
                "const": "topup"
              },
              "skuId": {
                "enum": [
                  "topup:pack_50",
                  "topup:pack_150",
                  "topup:pack_500",
                  "topup:pack_1000"
                ]
              },
              "catalogVersion": {
                "type": "string",
                "minLength": 1,
                "maxLength": 80
              },
              "idempotencyKey": {
                "type": "string",
                "minLength": 16,
                "maxLength": 128,
                "pattern": "^[A-Za-z0-9_-]+$"
              },
              "returnTarget": {
                "enum": [
                  "billing",
                  "generate",
                  "quiz"
                ]
              }
            },
            "additionalProperties": false
          },
          {
            "type": "object",
            "required": [
              "kind",
              "skuId",
              "catalogVersion",
              "idempotencyKey",
              "returnTarget"
            ],
            "properties": {
              "kind": {
                "const": "quiz"
              },
              "skuId": {
                "enum": [
                  "quiz:quiz_1week",
                  "quiz:quiz_2week",
                  "quiz:quiz_4week",
                  "quiz:quiz_12week"
                ]
              },
              "catalogVersion": {
                "type": "string",
                "minLength": 1,
                "maxLength": 80
              },
              "idempotencyKey": {
                "type": "string",
                "minLength": 16,
                "maxLength": 128,
                "pattern": "^[A-Za-z0-9_-]+$"
              },
              "returnTarget": {
                "enum": [
                  "billing",
                  "generate",
                  "quiz"
                ]
              }
            },
            "additionalProperties": false
          }
        ]
      },
      "Checkout": {
        "type": "object",
        "required": [
          "checkoutId",
          "url",
          "status",
          "statusUrl",
          "expiresAt",
          "amountMinor",
          "currency"
        ],
        "properties": {
          "checkoutId": {
            "type": "string",
            "format": "uuid"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "status": {
            "enum": [
              "pending",
              "processing",
              "paid_pending_review",
              "fulfilled",
              "failed",
              "expired",
              "refunded"
            ]
          },
          "statusUrl": {
            "type": "string"
          },
          "expiresAt": {
            "type": [
              "string",
              "null"
            ]
          },
          "amountMinor": {
            "type": "integer"
          },
          "currency": {
            "type": "string"
          },
          "renewalTerms": {}
        }
      },
      "CheckoutStatus": {
        "type": "object",
        "required": [
          "checkoutId",
          "status"
        ],
        "properties": {
          "checkoutId": {
            "type": "string",
            "format": "uuid"
          },
          "status": {
            "enum": [
              "pending",
              "processing",
              "paid_pending_review",
              "fulfilled",
              "failed",
              "expired",
              "refunded"
            ]
          },
          "statusUrl": {
            "type": "string"
          },
          "nextAction": {
            "type": "string"
          },
          "expiresAt": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "History": {
        "type": "object",
        "required": [
          "history"
        ],
        "properties": {
          "degraded": {
            "type": "boolean"
          },
          "history": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [],
              "properties": {
                "id": {
                  "type": "string"
                },
                "amount": {
                  "type": "number",
                  "description": "Major currency units"
                },
                "currency": {
                  "type": "string"
                },
                "status": {
                  "type": "string"
                },
                "productName": {
                  "type": "string"
                },
                "createdAt": {
                  "type": "string"
                },
                "invoiceUrl": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "provider": {
                  "type": "string",
                  "description": "Historical attribution only"
                }
              }
            }
          }
        }
      }
    }
  }
}