Subscription-Cycle

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/revolut/main/json-schema/revolut-subscription-cycle-schema.json",
  "title": "Subscription-Cycle",
  "x-generated": "2026-10-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/revolut-subscriptions-api-openapi.yml#/components/schemas/Subscription-Cycle",
  "type": "object",
  "required": [
    "id",
    "subscription_id",
    "plan_variation_id",
    "number",
    "state"
  ],
  "properties": {
    "id": {
      "$ref": "#/$defs/Subscription-Cycle-Id"
    },
    "subscription_id": {
      "$ref": "#/$defs/Subscription-Id"
    },
    "plan_variation_id": {
      "$ref": "#/$defs/Subscription-Plan-Variation-Id"
    },
    "plan_variation_phase_id": {
      "$ref": "#/$defs/Subscription-Plan-Phase-Id"
    },
    "number": {
      "$ref": "#/$defs/Cycle-Number"
    },
    "previous_cycle_id": {
      "$ref": "#/$defs/Previous-Cycle-Id"
    },
    "state": {
      "$ref": "#/$defs/Subscription-Cycle-State"
    },
    "start_date": {
      "$ref": "#/$defs/Subscription-Cycle-Start-Date"
    },
    "end_date": {
      "$ref": "#/$defs/Subscription-Cycle-End-Date"
    },
    "usage_cutoff_date": {
      "$ref": "#/$defs/Subscription-Cycle-Usage-Cutoff-Date"
    },
    "order_id": {
      "$ref": "#/$defs/Order-Id"
    },
    "post_billing_order_id": {
      "$ref": "#/$defs/Subscription-Cycle-Post-Billing-Order-Id"
    },
    "trial": {
      "$ref": "#/$defs/Subscription-Cycle-Trial"
    }
  },
  "$defs": {
    "Cycle-Number": {
      "type": "integer",
      "minimum": 1,
      "description": "The sequential cycle number within the subscription.\n\nStarts at `1` for the first cycle and increments with each new billing cycle."
    },
    "Order-Id": {
      "type": "string",
      "format": "uuid",
      "description": "Permanent order ID used to retrieve, capture, cancel, or refund an order after authorization."
    },
    "Previous-Cycle-Id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "description": "The unique identifier of the previous billing cycle.\n\nThis field is `null` for the first cycle in a subscription."
    },
    "Subscription-Cycle-End-Date": {
      "type": "string",
      "format": "date-time",
      "description": "The date and time the subscription cycle ends in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format."
    },
    "Subscription-Cycle-Id": {
      "type": "string",
      "format": "uuid",
      "description": "Unique identifier for the subscription cycle."
    },
    "Subscription-Cycle-Post-Billing-Order-Id": {
      "type": "string",
      "format": "uuid",
      "description": "The ID of the order created after the cycle's `usage_cutoff_date` to charge usage-based items accumulated during the cycle.\n\n| Scenario | Detail |\n| -------- | ------ |\n| Ongoing subscription | This order also acts as the next cycle's `order_id`, combining usage post-billing for the current cycle with pre-billing for the next. |\n| Last cycle | A standalone finishing order is created to charge all usage from this cycle. |\n| Subscription ended with unpaid cycles | The finishing order consolidates all outstanding usage charges, including any from previous cycles where payment failed. |\n\n:::note\nOnly present for cycles that include usage-based subscription items.\n:::"
    },
    "Subscription-Cycle-Start-Date": {
      "type": "string",
      "format": "date-time",
      "description": "The date and time the subscription cycle starts in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format."
    },
    "Subscription-Cycle-State": {
      "type": "string",
      "enum": [
        "pending",
        "active",
        "finished"
      ],
      "description": "The state of the subscription cycle.\n\n| State | Description |\n| ----- | ----------- |\n| `pending` | The cycle has been created but has not yet started. A cycle can enter this state automatically when usage is reported for a future cycle via `POST /api/subscription-usages`. |\n| `active` | The cycle is currently active and in progress. |\n| `finished` | The cycle has completed. |"
    },
    "Subscription-Cycle-Trial": {
      "type": "boolean",
      "description": "Indicates whether this billing cycle occurs during the subscription's trial period.\n\nThis value is automatically calculated by the system based on the cycle's timing relative to the subscription's trial period. Returns `true` if the cycle is within the trial period (before `trial_end_date`), otherwise `false`. \n\nTrial cycles typically have different billing behavior, such as reduced or zero charges.",
      "default": false
    },
    "Subscription-Cycle-Usage-Cutoff-Date": {
      "type": "string",
      "format": "date-time",
      "description": "The deadline for submitting or correcting usage records for this cycle, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.\n\nSet to 12 hours after the cycle's `end_date` by default. After this time, Revolut aggregates all reported usage records and creates the `post_billing_order_id` to initiate the charge.\n\n:::note\nOnly present for cycles that include usage-based subscription items.\n:::"
    },
    "Subscription-Id": {
      "type": "string",
      "format": "uuid",
      "description": "Unique identifier for the subscription."
    },
    "Subscription-Plan-Phase-Id": {
      "type": "string",
      "format": "uuid",
      "description": "Unique identifier for the subscription plan phase."
    },
    "Subscription-Plan-Variation-Id": {
      "type": "string",
      "format": "uuid",
      "description": "Unique identifier for the subscription plan variation."
    }
  }
}