---
title: "Get a plan"
openapi: "openapi POST /v1/plans.get"
---

import { DynamicParamField } from "/snippets/dynamic-param-field.jsx";
import { DynamicResponseField } from "/snippets/dynamic-response-field.jsx";
import { DynamicResponseExample } from "/snippets/dynamic-response-example.jsx";

Retrieves a single plan by its ID. Returns the latest version by default.

### Common Use Cases

<CodeGroup>

```typescript Get a plan
const plan = await autumn.plans.get({
  planId: "pro_plan"
});
```

```typescript Get a specific version
const plan = await autumn.plans.get({
  planId: "pro_plan",
  version: 2
});
```

</CodeGroup>

### Body Parameters

<DynamicParamField body="plan_id" type="string" required>
  The ID of the plan to retrieve.
</DynamicParamField>

<DynamicParamField body="version" type="number">
  The version of the plan to get. Defaults to the latest version.
</DynamicParamField>


### Response

<DynamicResponseField name="id" type="string">
  Unique identifier for the plan.
</DynamicResponseField>

<DynamicResponseField name="name" type="string">
  Display name of the plan.
</DynamicResponseField>

<DynamicResponseField name="description" type="string | null">
  Optional description of the plan.
</DynamicResponseField>

<DynamicResponseField name="group" type="string | null">
  Group identifier for organizing related plans. Plans in the same group are mutually exclusive.
</DynamicResponseField>

<DynamicResponseField name="version" type="number">
  Version number of the plan. Incremented when plan configuration changes.
</DynamicResponseField>

<DynamicResponseField name="add_on" type="boolean">
  Whether this is an add-on plan that can be attached alongside a main plan.
</DynamicResponseField>

<DynamicResponseField name="auto_enable" type="boolean">
  If true, this plan is automatically attached when a customer is created. Used for free plans.
</DynamicResponseField>

<DynamicResponseField name="price" type="object | null">
  Base recurring price for the plan. Null for free plans or usage-only plans.
  <Expandable title="properties">
    <DynamicResponseField name="amount" type="number">
      Base price amount for the plan.
    </DynamicResponseField>

    <DynamicResponseField name="interval" type="'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'">
      Billing interval (e.g. 'month', 'year').
    </DynamicResponseField>

    <DynamicResponseField name="interval_count" type="number">
      Number of intervals per billing cycle. Defaults to 1.
    </DynamicResponseField>

    <DynamicResponseField name="display" type="object">
      Display text for showing this price in pricing pages.
      <Expandable title="properties">
        <DynamicResponseField name="primary_text" type="string">
          Main display text (e.g. '$10' or '100 messages').
        </DynamicResponseField>

        <DynamicResponseField name="secondary_text" type="string">
          Secondary display text (e.g. 'per month' or 'then $0.5 per 100').
        </DynamicResponseField>

      </Expandable>
    </DynamicResponseField>

  </Expandable>
</DynamicResponseField>

<DynamicResponseField name="items" type="object[]">
  Feature configurations included in this plan. Each item defines included units, pricing, and reset behavior for a feature.
  <Expandable title="properties">
    <DynamicResponseField name="feature_id" type="string">
      The ID of the feature this item configures.
    </DynamicResponseField>

    <DynamicResponseField name="feature" type="object">
      The full feature object if expanded.
      <Expandable title="properties">
        <DynamicResponseField name="id" type="string">
          The ID of the feature, used to refer to it in other API calls like /track or /check.
        </DynamicResponseField>

        <DynamicResponseField name="name" type="string | null">
          The name of the feature.
        </DynamicResponseField>

        <DynamicResponseField name="type" type="'static' | 'boolean' | 'single_use' | 'continuous_use' | 'credit_system' | 'ai_credit_system'">
          The type of the feature
        </DynamicResponseField>

        <DynamicResponseField name="display" type="object | null">
          Singular and plural display names for the feature.
          <Expandable title="properties">
            <DynamicResponseField name="singular" type="string">
              The singular display name for the feature.
            </DynamicResponseField>

            <DynamicResponseField name="plural" type="string">
              The plural display name for the feature.
            </DynamicResponseField>

          </Expandable>
        </DynamicResponseField>

        <DynamicResponseField name="credit_schema" type="object[] | null">
          Credit cost schema for credit system features.
          <Expandable title="properties">
            <DynamicResponseField name="metered_feature_id" type="string">
              The ID of the metered feature (should be a single_use feature).
            </DynamicResponseField>

            <DynamicResponseField name="credit_cost" type="number">
              The credit cost of the metered feature.
            </DynamicResponseField>

          </Expandable>
        </DynamicResponseField>

        <DynamicResponseField name="archived" type="boolean | null">
          Whether or not the feature is archived.
        </DynamicResponseField>

      </Expandable>
    </DynamicResponseField>

    <DynamicResponseField name="included" type="number">
      Number of free units included. For consumable features, balance resets to this number each interval.
    </DynamicResponseField>

    <DynamicResponseField name="unlimited" type="boolean">
      Whether the customer has unlimited access to this feature.
    </DynamicResponseField>

    <DynamicResponseField name="reset" type="object | null">
      Reset configuration for consumable features. Null for non-consumable features like seats where usage persists across billing cycles.
      <Expandable title="properties">
        <DynamicResponseField name="interval" type="'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'">
          The interval at which the feature balance resets (e.g. 'month', 'year'). For consumable features, usage resets to 0 and included units are restored.
        </DynamicResponseField>

        <DynamicResponseField name="interval_count" type="number">
          Number of intervals between resets. Defaults to 1.
        </DynamicResponseField>

      </Expandable>
    </DynamicResponseField>

    <DynamicResponseField name="price" type="object | null">
      Pricing configuration for usage beyond included units. Null if feature is entirely free.
      <Expandable title="properties">
        <DynamicResponseField name="amount" type="number">
          Price per billing_units after included usage is consumed. Mutually exclusive with tiers.
        </DynamicResponseField>

        <DynamicResponseField name="tiers" type="object[]">
          Tiered pricing configuration. Each tier's 'to' INCLUDES the included amount. Either 'tiers' or 'amount' is required.
          <Expandable title="properties">
            <DynamicResponseField name="to" type="number" />

            <DynamicResponseField name="amount" type="number" />

            <DynamicResponseField name="flat_amount" type="number" />

          </Expandable>
        </DynamicResponseField>

        <DynamicResponseField name="tier_behavior" type="'graduated' | 'volume'" />

        <DynamicResponseField name="interval" type="'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'">
          Billing interval for this price. For consumable features, should match reset.interval.
        </DynamicResponseField>

        <DynamicResponseField name="interval_count" type="number">
          Number of intervals per billing cycle. Defaults to 1.
        </DynamicResponseField>

        <DynamicResponseField name="billing_units" type="number">
          Number of units per price increment. Usage is rounded UP to the nearest billing_units when billed (e.g. billing_units=100 means 101 usage rounds to 200).
        </DynamicResponseField>

        <DynamicResponseField name="billing_method" type="'prepaid' | 'usage_based'">
          'prepaid' for features like seats where customers pay upfront, 'usage_based' for pay-as-you-go after included usage.
        </DynamicResponseField>

        <DynamicResponseField name="max_purchase" type="number | null">
          Maximum units a customer can purchase beyond included. E.g. if included=100 and max_purchase=300, customer can use up to 400 total before usage is capped. Null for no limit.
        </DynamicResponseField>

      </Expandable>
    </DynamicResponseField>

    <DynamicResponseField name="display" type="object">
      Display text for showing this item in pricing pages.
      <Expandable title="properties">
        <DynamicResponseField name="primary_text" type="string">
          Main display text (e.g. '$10' or '100 messages').
        </DynamicResponseField>

        <DynamicResponseField name="secondary_text" type="string">
          Secondary display text (e.g. 'per month' or 'then $0.5 per 100').
        </DynamicResponseField>

      </Expandable>
    </DynamicResponseField>

    <DynamicResponseField name="rollover" type="object">
      Rollover configuration for unused units. If set, unused included units roll over to the next period.
      <Expandable title="properties">
        <DynamicResponseField name="max" type="number | null">
          Maximum rollover units. Null for unlimited rollover.
        </DynamicResponseField>

        <DynamicResponseField name="max_percentage" type="number | null">
          Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max.
        </DynamicResponseField>

        <DynamicResponseField name="expiry_duration_type" type="'month' | 'forever'">
          When rolled over units expire.
        </DynamicResponseField>

        <DynamicResponseField name="expiry_duration_length" type="number">
          Number of periods before expiry.
        </DynamicResponseField>

      </Expandable>
    </DynamicResponseField>

  </Expandable>
</DynamicResponseField>

<DynamicResponseField name="free_trial" type="object">
  Free trial configuration. If set, new customers can try this plan before being charged.
  <Expandable title="properties">
    <DynamicResponseField name="duration_length" type="number">
      Number of duration_type periods the trial lasts.
    </DynamicResponseField>

    <DynamicResponseField name="duration_type" type="'day' | 'month' | 'year'">
      Unit of time for the trial duration ('day', 'month', 'year').
    </DynamicResponseField>

    <DynamicResponseField name="card_required" type="boolean">
      Whether a payment method is required to start the trial. If true, customer will be charged after trial ends.
    </DynamicResponseField>

    <DynamicResponseField name="on_end" type="'bill' | 'revert'">
      Behavior when the trial ends. 'bill' charges the customer (default). 'revert' expires the trial and restores the customer's previous plan.
    </DynamicResponseField>

  </Expandable>
</DynamicResponseField>

<DynamicResponseField name="created_at" type="number">
  Unix timestamp (ms) when the plan was created.
</DynamicResponseField>

<DynamicResponseField name="env" type="'sandbox' | 'live'">
  Environment this plan belongs to ('sandbox' or 'live').
</DynamicResponseField>

<DynamicResponseField name="archived" type="boolean">
  Whether the plan is archived. Archived plans cannot be attached to new customers.
</DynamicResponseField>

<DynamicResponseField name="base_variant_id" type="string | null">
  If this is a variant, the ID of the base plan it was created from.
</DynamicResponseField>

<DynamicResponseField name="config" type="object">
  Miscellaneous plan-level configuration flags.
  <Expandable title="properties">
    <DynamicResponseField name="ignore_past_due" type="boolean">
      If true, entitlements attached to this plan will still reset on schedule even when the customer's product is in a past_due state.
    </DynamicResponseField>

  </Expandable>
</DynamicResponseField>

<DynamicResponseField name="customer_eligibility" type="object">
  <Expandable title="properties">
    <DynamicResponseField name="trial_available" type="boolean">
      Whether the trial on this plan is available to this customer. For example, if the customer used the trial in the past, this will be false.
    </DynamicResponseField>

    <DynamicResponseField name="status" type="'active' | 'scheduled'">
      The customer's current status with this plan. 'active' if attached, 'scheduled' if pending activation.
    </DynamicResponseField>

    <DynamicResponseField name="canceling" type="boolean">
      Whether the customer's active instance of this plan is set to cancel.
    </DynamicResponseField>

    <DynamicResponseField name="trialing" type="boolean">
      Whether the customer is currently on a free trial of this plan.
    </DynamicResponseField>

    <DynamicResponseField name="attach_action" type="'activate' | 'upgrade' | 'downgrade' | 'none' | 'purchase'">
      The action that would occur if this plan were attached to the customer.
    </DynamicResponseField>

  </Expandable>
</DynamicResponseField>


<ResponseExample>
```json 200
{
  "id": "pro",
  "name": "Pro Plan",
  "description": null,
  "group": null,
  "version": 1,
  "addOn": false,
  "autoEnable": false,
  "price": {
    "amount": 10,
    "interval": "month",
    "display": {
      "primaryText": "$10",
      "secondaryText": "per month"
    }
  },
  "items": [
    {
      "featureId": "messages",
      "included": 100,
      "unlimited": false,
      "reset": {
        "interval": "month"
      },
      "price": {
        "amount": 0.5,
        "interval": "month",
        "billingUnits": 100,
        "billingMethod": "usage_based",
        "maxPurchase": null
      },
      "display": {
        "primaryText": "100 messages",
        "secondaryText": "then $0.5 per 100 messages"
      }
    },
    {
      "featureId": "users",
      "included": 0,
      "unlimited": false,
      "reset": null,
      "price": {
        "amount": 10,
        "interval": "month",
        "billingUnits": 1,
        "billingMethod": "prepaid",
        "maxPurchase": null
      },
      "display": {
        "primaryText": "$10 per Users"
      }
    }
  ],
  "createdAt": 1771513979217,
  "env": "sandbox",
  "archived": false,
  "baseVariantId": null,
  "config": {
    "ignore_past_due": false
  }
}
```
</ResponseExample>