Skip to main content

List plans​

This endpoint returns a list of all plans for an account in a list format. The list of plans is ordered starting from the most recently created plan. The response also includes pagination_metadata, which lets the caller retrieve the next page of results if they exist.

Query Parameters
    limit integer

    Default value: 20

    cursor string
    status string

    Possible values: [active, archived, draft]

    created_at[gte] date-time
    created_at[gt] date-time
    created_at[lt] date-time
    created_at[lte] date-time
Responses

OK

Response Headers
    Schema
      data object[] required
    • Array [
      • metadata object required

      User specified key-value pairs for the resource. If not present, this defaults to an empty dictionary. Individual keys can be removed by setting the value to null, and the entire metadata mapping can be cleared by setting metadata to null.

      property name* string
      id string required
      name string required
      description string required
      maximum_amount string nullable required
      minimum_amount string nullable required
      created_at date-time required
      status string required

      Possible values: [active, archived, draft]

      maximum object nullable
      maximum_amount string required

      Maximum amount applied

      applies_to_price_ids string[] required

      List of price_ids that this maximum amount applies to. For plan/plan phase maximums, this can be a subset of prices.

      minimum object nullable
      minimum_amount string required

      Minimum amount applied

      applies_to_price_ids string[] required

      List of price_ids that this minimum amount applies to. For plan/plan phase minimums, this can be a subset of prices.

      discount object nullable
      oneOf
      discount_type string required

      Possible values: [percentage]

      applies_to_price_ids string[] required

      List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.

      reason string nullable
      percentage_discount number required

      Possible values: <= 1

      Only available if discount_type is percentage. This is a number between 0 and 1.

      product object required
      created_at date-time required
      id string required
      name string required
      trial_config object required
      trial_period integer nullable required
      trial_period_unit string required

      Possible values: [days]

      plan_phases object[] nullable required
    • Array [
      • id string required
      description string nullable required
      duration integer nullable required

      How many terms of length duration_unit this phase is active for. If null, this phase is evergreen and active indefinitely

      duration_unit string nullable required

      Possible values: [daily, monthly, quarterly, annual]

      name string required
      order integer required

      Determines the ordering of the phase in a plan's lifecycle. 1 = first phase.

      minimum object nullable
      minimum_amount string required

      Minimum amount applied

      applies_to_price_ids string[] required

      List of price_ids that this minimum amount applies to. For plan/plan phase minimums, this can be a subset of prices.

      maximum object nullable
      maximum_amount string required

      Maximum amount applied

      applies_to_price_ids string[] required

      List of price_ids that this maximum amount applies to. For plan/plan phase maximums, this can be a subset of prices.

      maximum_amount string nullable required
      minimum_amount string nullable required
      discount object nullable
      oneOf
      discount_type string required

      Possible values: [percentage]

      applies_to_price_ids string[] required

      List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.

      reason string nullable
      percentage_discount number required

      Possible values: <= 1

      Only available if discount_type is percentage. This is a number between 0 and 1.

    • ]
      • base_plan object nullable
      id string nullable required
      external_plan_id string nullable required

      An optional user-defined ID for this plan resource, used throughout the system as an alias for this Plan. Use this field to identify a plan by an existing identifier in your system.

      name string nullable required
      base_plan_id string nullable required

      The parent plan id if the given plan was created by overriding one or more of the parent's prices

      external_plan_id string nullable required

      An optional user-defined ID for this plan resource, used throughout the system as an alias for this Plan. Use this field to identify a plan by an existing identifier in your system.

      currency string required

      An ISO 4217 currency string or custom pricing unit (credits) for this plan's prices.

      invoicing_currency string required

      An ISO 4217 currency string for which this plan is billed in. Matches currency unless currency is a custom pricing unit.

      net_terms integer nullable required

      Determines the difference between the invoice issue date and the due date. A value of "0" here signifies that invoices are due on issue, whereas a value of "30" means that the customer has a month to pay the invoice before its overdue. Note that individual subscriptions or invoices may set a different net terms configuration.

      default_invoice_memo string nullable required

      The default memo text on the invoices corresponding to subscriptions on this plan. Note that each subscription may configure its own memo.

      prices object[] required

      Prices for this plan. If the plan has phases, this includes prices across all phases of the plan.

    • Array [
      • oneOf
      id string required
      name string required
      external_price_id string nullable required
      price_type string required

      Possible values: [usage_price, fixed_price]

      model_type string required

      Possible values: [unit]

      created_at date-time required
      cadence string required

      Possible values: [one_time, monthly, quarterly, annual]

      billable_metric object nullable
      id string required
      fixed_price_quantity number nullable required
      plan_phase_order integer nullable required
      currency string required
      item object required
      id string required
      name string required
      discount object nullable
      oneOf
      discount_type string required

      Possible values: [percentage]

      applies_to_price_ids string[] required

      List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.

      reason string nullable
      percentage_discount number required

      Possible values: <= 1

      Only available if discount_type is percentage. This is a number between 0 and 1.

      minimum object nullable
      minimum_amount string required

      Minimum amount applied

      applies_to_price_ids string[] required

      List of price_ids that this minimum amount applies to. For plan/plan phase minimums, this can be a subset of prices.

      minimum_amount string nullable required
      maximum object nullable
      maximum_amount string required

      Maximum amount applied

      applies_to_price_ids string[] required

      List of price_ids that this maximum amount applies to. For plan/plan phase maximums, this can be a subset of prices.

      maximum_amount string nullable required
      unit_config object required
      unit_amount string required

      Rate per unit of usage

      scaling_factor number nullable

      Multiplier to scale rated quantity by

    • ]
    • ]
      • pagination_metadata object required
      has_more boolean required
      next_cursor string nullable required
    Loading...