Subscription

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/xero/main/json-schema/xero-subscription-schema.json",
  "title": "Subscription",
  "x-generated": "2026-10-20",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/xero-app-store-api-openapi.yml#/components/schemas/Subscription",
  "type": "object",
  "properties": {
    "currentPeriodEnd": {
      "description": "End of the current period that the subscription has been invoiced for.\n",
      "format": "date-time",
      "type": "string",
      "x-is-datetime": true
    },
    "endDate": {
      "description": "If the subscription has been canceled, this is the date when the subscription ends. If null, the subscription is active and has not been cancelled",
      "format": "date-time",
      "type": "string",
      "x-is-datetime": true
    },
    "id": {
      "description": "The unique identifier of the subscription",
      "format": "uuid",
      "type": "string"
    },
    "organisationId": {
      "description": "The Xero generated unique identifier for the organisation",
      "format": "uuid",
      "type": "string"
    },
    "plans": {
      "description": "List of plans for the subscription.",
      "type": "array",
      "items": {
        "$ref": "#/$defs/Plan"
      }
    },
    "startDate": {
      "description": "Date when the subscription was first created.",
      "format": "date-time",
      "type": "string",
      "x-is-datetime": true
    },
    "status": {
      "description": "Status of the subscription. Available statuses are ACTIVE, CANCELED, and PAST_DUE.",
      "type": "string",
      "enum": [
        "ACTIVE",
        "CANCELED",
        "PAST_DUE"
      ]
    },
    "testMode": {
      "description": "Boolean used to indicate if the subscription is in test mode",
      "type": "boolean"
    }
  },
  "required": [
    "id",
    "organisationId",
    "status",
    "startDate",
    "currentPeriodEnd",
    "plans"
  ],
  "$defs": {
    "Plan": {
      "type": "object",
      "properties": {
        "id": {
          "description": "The unique identifier of the plan",
          "format": "uuid",
          "type": "string"
        },
        "name": {
          "description": "The name of the plan. It is used in the invoice line item\ndescription.\n",
          "type": "string"
        },
        "status": {
          "description": "Status of the plan. Available statuses are ACTIVE, CANCELED, and\nPENDING_ACTIVATION.\n",
          "type": "string",
          "enum": [
            "ACTIVE",
            "CANCELED",
            "PENDING_ACTIVATION"
          ]
        },
        "subscriptionItems": {
          "description": "List of the subscription items belonging to the plan. It does not\ninclude cancelled subscription items.\n",
          "items": {
            "$ref": "#/$defs/SubscriptionItem"
          },
          "type": "array"
        }
      },
      "required": [
        "id",
        "name",
        "status",
        "subscriptionItems"
      ]
    },
    "Price": {
      "type": "object",
      "properties": {
        "amount": {
          "description": "The net (before tax) amount.",
          "type": "number",
          "format": "double",
          "x-is-money": true
        },
        "currency": {
          "description": "The currency of the price.",
          "type": "string"
        },
        "id": {
          "description": "The unique identifier of the price.",
          "format": "uuid",
          "type": "string"
        }
      },
      "required": [
        "id",
        "amount",
        "currency"
      ]
    },
    "Product": {
      "properties": {
        "id": {
          "description": "The unique identifier for the product",
          "type": "string",
          "format": "uuid"
        },
        "name": {
          "description": "The name of the product",
          "type": "string"
        },
        "seatUnit": {
          "description": "The unit of the per seat product. e.g. \"user\", \"organisation\", \"SMS\", etc",
          "type": "string"
        },
        "type": {
          "description": "The pricing model of the product:\n* FIXED: Customers are charged a fixed amount for each billing period\n* PER_SEAT: Customers are charged based on the number of units they purchase\n* METERED: Customers are charged per use of this product\n* SIMPLE: Customers are charged on a fixed amount for each billing period with an optional add-on feature\n",
          "type": "string",
          "enum": [
            "FIXED",
            "PER_SEAT",
            "METERED",
            "SIMPLE"
          ]
        },
        "usageUnit": {
          "description": "The unit of the usage product. e.g. \"user\", \"minutes\", \"SMS\", etc",
          "type": "string"
        }
      }
    },
    "SubscriptionItem": {
      "type": "object",
      "properties": {
        "endDate": {
          "description": "Date when the subscription to this product will end",
          "format": "date-time",
          "type": "string",
          "x-is-datetime": true
        },
        "id": {
          "description": "The unique identifier of the subscription item.",
          "format": "uuid",
          "type": "string"
        },
        "price": {
          "description": "The price of the product subscribed to.",
          "$ref": "#/$defs/Price"
        },
        "product": {
          "description": "The product subscribed to.",
          "$ref": "#/$defs/Product"
        },
        "quantity": {
          "description": "The quantity of the item. For a fixed product, it is 1. For a per-seat product, it is a positive integer. For metered products, it is always null.",
          "type": "integer"
        },
        "startDate": {
          "description": "Date the subscription started, or will start. Note: this could be in\nthe future for downgrades or reduced number of seats that haven't taken effect yet.\n",
          "format": "date-time",
          "type": "string",
          "x-is-datetime": true
        },
        "status": {
          "description": "Status of the subscription item. Available statuses are ACTIVE, CANCELED, and\nPENDING_ACTIVATION.\n",
          "type": "string",
          "enum": [
            "ACTIVE",
            "CANCELED",
            "PENDING_ACTIVATION"
          ]
        },
        "testMode": {
          "description": "If the subscription is a test subscription",
          "type": "boolean"
        }
      },
      "required": [
        "id",
        "startDate",
        "product",
        "price",
        "status"
      ]
    }
  }
}