Skip to main content
PUT
/
plans
/
external_plan_id
/
{external_plan_id}
Update plan by external ID
curl --request PUT \
  --url https://api.withorb.com/v1/plans/external_plan_id/{external_plan_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "metadata": {},
  "external_plan_id": "<string>"
}'
{
  "metadata": {},
  "id": "<string>",
  "name": "<string>",
  "description": "<string>",
  "maximum_amount": "<string>",
  "minimum_amount": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "status": "active",
  "maximum": {
    "maximum_amount": "<string>",
    "filters": [
      {
        "field": "price_id",
        "operator": "includes",
        "values": [
          "<any>"
        ]
      }
    ],
    "applies_to_price_ids": [
      "<string>"
    ]
  },
  "minimum": {
    "minimum_amount": "<string>",
    "filters": [
      {
        "field": "price_id",
        "operator": "includes",
        "values": [
          "<any>"
        ]
      }
    ],
    "applies_to_price_ids": [
      "<string>"
    ]
  },
  "discount": {
    "discount_type": "percentage",
    "applies_to_price_ids": [
      "h74gfhdjvn7ujokd",
      "7hfgtgjnbvc3ujkl"
    ],
    "filters": [
      {
        "field": "<any>",
        "operator": "<any>",
        "values": "<any>"
      }
    ],
    "reason": "<string>",
    "percentage_discount": 0.15
  },
  "product": {
    "created_at": "2023-11-07T05:31:56Z",
    "id": "<string>",
    "name": "<string>"
  },
  "version": 123,
  "trial_config": {
    "trial_period": 123,
    "trial_period_unit": "days"
  },
  "plan_phases": [
    {
      "id": "<string>",
      "description": "<string>",
      "duration": 123,
      "duration_unit": "daily",
      "name": "<string>",
      "order": 123,
      "minimum": {
        "minimum_amount": "<string>",
        "filters": [
          {
            "field": "price_id",
            "operator": "includes",
            "values": [
              "<any>"
            ]
          }
        ],
        "applies_to_price_ids": [
          "<string>"
        ]
      },
      "maximum": {
        "maximum_amount": "<string>",
        "filters": [
          {
            "field": "price_id",
            "operator": "includes",
            "values": [
              "<any>"
            ]
          }
        ],
        "applies_to_price_ids": [
          "<string>"
        ]
      },
      "maximum_amount": "<string>",
      "minimum_amount": "<string>",
      "discount": {
        "discount_type": "percentage",
        "applies_to_price_ids": [
          "h74gfhdjvn7ujokd",
          "7hfgtgjnbvc3ujkl"
        ],
        "filters": [
          {
            "field": "<any>",
            "operator": "<any>",
            "values": "<any>"
          }
        ],
        "reason": "<string>",
        "percentage_discount": 0.15
      }
    }
  ],
  "base_plan": {
    "id": "m2t5akQeh2obwxeU",
    "external_plan_id": "m2t5akQeh2obwxeU",
    "name": "Example plan"
  },
  "base_plan_id": "<string>",
  "external_plan_id": "<string>",
  "currency": "<string>",
  "invoicing_currency": "<string>",
  "net_terms": 123,
  "default_invoice_memo": "<string>",
  "prices": [
    {
      "model_type": "unit",
      "unit_config": {
        "unit_amount": "<string>",
        "prorated": false
      },
      "metadata": {},
      "id": "<string>",
      "name": "<string>",
      "external_price_id": "<string>",
      "replaces_price_id": "<string>",
      "price_type": "usage_price",
      "created_at": "2023-11-07T05:31:56Z",
      "cadence": "one_time",
      "billing_mode": "in_advance",
      "billing_cycle_configuration": {
        "duration": 123,
        "duration_unit": "day"
      },
      "invoicing_cycle_configuration": {
        "duration": 123,
        "duration_unit": "day"
      },
      "billable_metric": {
        "id": "<string>"
      },
      "dimensional_price_configuration": {
        "dimensional_price_group_id": "<string>",
        "dimension_values": [
          "<string>"
        ]
      },
      "fixed_price_quantity": 123,
      "plan_phase_order": 123,
      "currency": "<string>",
      "conversion_rate": 123,
      "conversion_rate_config": {
        "conversion_rate_type": "unit",
        "unit_config": {
          "unit_amount": "<string>"
        }
      },
      "item": {
        "id": "<string>",
        "name": "<string>"
      },
      "credit_allocation": {
        "currency": "<string>",
        "allows_rollover": true,
        "custom_expiration": {
          "duration": 123,
          "duration_unit": "day"
        },
        "filters": [
          {
            "field": "<any>",
            "operator": "<any>",
            "values": "<any>"
          }
        ]
      },
      "composite_price_filters": [
        {
          "field": "<any>",
          "operator": "<any>",
          "values": "<any>"
        }
      ],
      "discount": {
        "discount_type": "percentage",
        "applies_to_price_ids": [
          "h74gfhdjvn7ujokd",
          "7hfgtgjnbvc3ujkl"
        ],
        "filters": [
          {
            "field": "<any>",
            "operator": "<any>",
            "values": "<any>"
          }
        ],
        "reason": "<string>",
        "percentage_discount": 0.15
      },
      "minimum": {
        "minimum_amount": "<string>",
        "filters": [
          {
            "field": "price_id",
            "operator": "includes",
            "values": [
              "<any>"
            ]
          }
        ],
        "applies_to_price_ids": [
          "<string>"
        ]
      },
      "minimum_amount": "<string>",
      "maximum": {
        "maximum_amount": "<string>",
        "filters": [
          {
            "field": "price_id",
            "operator": "includes",
            "values": [
              "<any>"
            ]
          }
        ],
        "applies_to_price_ids": [
          "<string>"
        ]
      },
      "maximum_amount": "<string>"
    }
  ],
  "adjustments": [
    {
      "id": "<string>",
      "is_invoice_level": true,
      "filters": [
        {
          "field": "<any>",
          "operator": "<any>",
          "values": "<any>"
        }
      ],
      "applies_to_price_ids": [
        "<string>"
      ],
      "reason": "<string>",
      "replaces_adjustment_id": "<string>",
      "adjustment_type": "usage_discount",
      "usage_discount": 123,
      "plan_phase_order": 123
    }
  ]
}

Authorizations

​
Authorization
string
header
required

API Keys can be issued in the Orb's web application.

Path Parameters

​
external_plan_id
string
required

Body

application/json
​
metadata
object | null

User-specified key/value pairs for the resource. Individual keys can be removed by setting the value to null, and the entire metadata mapping can be cleared by setting metadata to null.

​
external_plan_id
string | null

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.

Response

OK

The Plan resource represents a plan that can be subscribed to by a customer. Plans define the billing behavior of the subscription. You can see more about how to configure prices in the Price resource.

​
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.

​
id
string
required
​
name
string
required
​
description
string
required
​
maximum_amount
string | null
required
deprecated
​
minimum_amount
string | null
required
deprecated
​
created_at
string<date-time>
required
​
status
enum<string>
required
Available options:
active,
archived,
draft
​
maximum
object | null
required
deprecated
​
minimum
object | null
required
deprecated
​
discount
object | null
required
deprecated
  • PercentageDiscount
  • TrialDiscount
  • UsageDiscount
  • AmountDiscount
​
product
object
required
​
version
integer
required
​
trial_config
object
required
​
plan_phases
PlanPhase · object[] | null
required
​
base_plan
object | null
required
deprecated

Legacy field representing the parent plan if the current plan is a 'child plan', overriding prices from the parent.

​
base_plan_id
string | null
required
deprecated

Legacy field representing the parent plan ID if the current plan is a 'child plan', overriding prices from the parent.

​
external_plan_id
string | null
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
deprecated

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 | null
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 | null
required

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

​
prices
Prices · array
required

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

  • UnitPrice
  • TieredPrice
  • BulkPrice
  • BulkWithFiltersPrice
  • PackagePrice
  • MatrixPrice
  • ThresholdTotalAmountPrice
  • TieredPackagePrice
  • TieredWithMinimumPrice
  • GroupedTieredPrice
  • TieredPackageWithMinimumPrice
  • PackageWithAllocationPrice
  • UnitWithPercentPrice
  • MatrixWithAllocationPrice
  • TieredWithProrationPrice
  • UnitWithProrationPrice
  • GroupedAllocationPrice
  • BulkWithProrationPrice
  • GroupedWithProratedMinimumPrice
  • GroupedWithMeteredMinimumPrice
  • GroupedWithMinMaxThresholdsPrice
  • MatrixWithDisplayNamePrice
  • GroupedTieredPackagePrice
  • MaxGroupTieredPackagePrice
  • ScalableMatrixWithUnitPricingPrice
  • ScalableMatrixWithTieredPricingPrice
  • CumulativeGroupedBulkPrice
  • CumulativeGroupedAllocationPrice
  • MinimumCompositePrice
  • PercentCompositePrice
  • EventOutputPrice
​
adjustments
Adjustments · array
required

Adjustments for this plan. If the plan has phases, this includes adjustments across all phases of the plan.

  • PlanPhaseUsageDiscountAdjustment
  • PlanPhaseAmountDiscountAdjustment
  • PlanPhasePercentageDiscountAdjustment
  • PlanPhaseMinimumAdjustment
  • PlanPhaseMaximumAdjustment