---
title: "Get plan by ID"
method: GET
path: "/plans/{planId}"
tags: ["plans"]
---

# Get plan by ID

`GET /plans/{planId}`

## Request

- Base URL: `https://api.agentpaid.io/api/v1`
- URL: `https://api.agentpaid.io/api/v1/plans/{planId}`
- Auth: HTTP bearer

## Path parameters

- `planId` string, uuid, required

## Response `200`

Success response

- Plan: A plan containing products and their attributes
  - `id` string, uuid, required: The unique identifier of the plan
  - `organizationId` string, uuid, required: The organization ID that owns this plan
  - `planGroupId` string, uuid, required: The plan group ID this plan belongs to
  - `name` string, required: The name of the plan
  - `description` string, nullable: The description of the plan
  - `type` 'flat' | 'usage' | 'credit', required: The type of plan (flat for fixed pricing, usage for usage-based, credit for prepaid credits)
  - `pricing` PlanPricing, required: The pricing configuration for a plan. Uses the same PricePoints structure as product pricing.
    - `PricePoints` object, required: Price points keyed by currency code (e.g., "USD", "EUR")
    - `billingFrequency` 'monthly' | 'quarterly' | 'semi-annually' | 'yearly' | 'custom', required: The billing frequency for the plan
    - `billingFrequencyCustomMonths` number, double: Custom billing frequency in months (when billingFrequency is "custom")
  - `nextPlanId` string, uuid, nullable: The ID of the next plan in the sequence
  - `prevPlanId` string, uuid, nullable: The ID of the previous plan in the sequence
  - `createdAt` string, date-time, required: When the plan was created
  - `updatedAt` string, date-time, required: When the plan was last updated
  - `planProducts` PlanPlanProductsItems[]: The products included in this plan
    - `id` string, uuid
    - `organizationId` string, uuid
    - `planId` string, uuid
    - `productId` string, uuid
    - `createdAt` string, date-time
    - `updatedAt` string, date-time
    - `product` Product: A product in the Paid system (previously called Agent)
      - `id` string, uuid, required
      - `externalId` string, nullable
      - `displayId` string: Human-readable display ID
      - `organizationId` string, uuid, required
      - `name` string, required
      - `description` string, nullable
      - `type` 'agent' | 'product' | 'prepaidCreditBundle', required: The type of product
      - `active` boolean, required
      - `productCode` string, nullable
      - `ProductAttribute` AgentAttribute[]: Pricing attributes for this product
        - `name` string, required
        - `active` boolean, required
        - `pricing` Pricing, required
          - `eventName` string
          - `taxable` boolean, required
          - `creditCost` number, double
          - `chargeType` 'oneTime' | 'recurring' | 'usage' | 'seatBased', required
          - `pricingModel` 'PerUnit' | 'VolumePricing' | 'GraduatedPricing' | 'PrepaidCredits', required
          - `billingFrequency` 'monthly' | 'quarterly' | 'annual', required
          - `pricePoints` object, required
      - `metadata` object, nullable
      - `createdAt` string, date-time
      - `updatedAt` string, date-time
    - `planProductAttribute` PlanPlanProductsItemsPlanProductAttributeItems[]: The product attributes with pricing for this plan
      - `id` string, uuid
      - `organizationId` string, uuid
      - `planProductId` string, uuid
      - `productAttributeId` string, uuid
      - `pricing` object: The pricing configuration for this attribute
      - `createdAt` string, date-time
      - `updatedAt` string, date-time

## Other responses

- `403`: Forbidden - Invalid or missing API key
- `404`: Plan not found

---

[API](https://skmtc.dev/paid/apis/paid-2.md) - [All operations](https://skmtc.dev/paid/apis/paid-2/llms.txt) - [OpenAPI document](https://skmtc.dev/paid/apis/paid-2/revisions/dbdf4a60ed27?raw)