Class: Orb::Resources::Plans

Inherits:
Object
  • Object
show all
Defined in:
lib/orb/resources/plans.rb,
lib/orb/resources/plans/migrations.rb,
lib/orb/resources/plans/external_plan_id.rb,
sig/orb/resources/plans.rbs,
sig/orb/resources/plans/migrations.rbs,
sig/orb/resources/plans/external_plan_id.rbs

Overview

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.

Defined Under Namespace

Classes: ExternalPlanID, Migrations

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(client:) ⇒ Plans

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of Plans.

Parameters:



183
184
185
186
187
 
# File 'lib/orb/resources/plans.rb', line 183

def initialize(client:)
  @client = client
  @external_plan_id = Orb::Resources::Plans::ExternalPlanID.new(client: client)
  @migrations = Orb::Resources::Plans::Migrations.new(client: client)
end

Instance Attribute Details

#external_plan_id ⇒ Orb::Resources::Plans::ExternalPlanID (readonly)

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.

Returns:



15
16
17
 
# File 'lib/orb/resources/plans.rb', line 15

def external_plan_id
  @external_plan_id
end

#migrations ⇒ Orb::Resources::Plans::Migrations (readonly)

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.

Returns:



22
23
24
 
# File 'lib/orb/resources/plans.rb', line 22

def migrations
  @migrations
end

Instance Method Details

#create(currency:, name:, prices:, adjustments: nil, default_invoice_memo: nil, description: nil, external_plan_id: nil, metadata: nil, net_terms: nil, plan_phases: nil, status: nil, request_options: {}) ⇒ Orb::Models::Plan

Some parameter documentations has been truncated, see Models::PlanCreateParams for more details.

This endpoint allows creation of plans including their prices.

Parameters:

  • currency (String) —

    An ISO 4217 currency string for invoices generated by subscriptions on this plan

  • name (String)
  • prices (Array<Orb::Models::PlanCreateParams::Price>) —

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

  • adjustments (Array<Orb::Models::PlanCreateParams::Adjustment>, nil) —

    Adjustments for this plan. If the plan has phases, this includes adjustments acr

  • default_invoice_memo (String, nil) —

    Free-form text which is available on the invoice PDF and the Orb invoice portal.

  • description (String, nil) —

    An optional user-defined description of the plan.

  • external_plan_id (String, nil)
  • metadata (Hash{Symbol=>String, nil}, nil) —

    User-specified key/value pairs for the resource. Individual keys can be removed

  • net_terms (Integer, nil) —

    The net terms determines the difference between the invoice date and the issue d

  • plan_phases (Array<Orb::Models::PlanCreateParams::PlanPhase>, nil) —

    Configuration of pre-defined phases, each with their own prices and adjustments.

  • status (Symbol, Orb::Models::PlanCreateParams::Status) —

    The status of the plan to create (either active or draft). If not specified, thi

  • request_options (Orb::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



58
59
60
61
 
# File 'lib/orb/resources/plans.rb', line 58

def create(params)
  parsed, options = Orb::PlanCreateParams.dump_request(params)
  @client.request(method: :post, path: "plans", body: parsed, model: Orb::Plan, options: options)
end

#fetch(plan_id, request_options: {}) ⇒ Orb::Models::Plan

This endpoint is used to fetch plan details given a plan identifier. It returns information about the prices included in the plan and their configuration, as well as the product that the plan is attached to.

Serialized prices

Orb supports a few different pricing models out of the box. Each of these models is serialized differently in a given Price object. The model_type field determines the key for the configuration object that is present. A detailed explanation of price types can be found in the Price schema.

Phases

Orb supports plan phases, also known as contract ramps. For plans with phases, the serialized prices refer to all prices across all phases.

Parameters:

Returns:

See Also:



171
172
173
174
175
176
177
178
 
# File 'lib/orb/resources/plans.rb', line 171

def fetch(plan_id, params = {})
  @client.request(
    method: :get,
    path: ["plans/%1$s", plan_id],
    model: Orb::Plan,
    options: params[:request_options]
  )
end

#list(created_at_gt: nil, created_at_gte: nil, created_at_lt: nil, created_at_lte: nil, cursor: nil, limit: nil, status: nil, request_options: {}) ⇒ Orb::Internal::Page<Orb::Models::Plan>

Some parameter documentations has been truncated, see Models::PlanListParams for more details.

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.

Parameters:

  • created_at_gt (Time, nil)
  • created_at_gte (Time, nil)
  • created_at_lt (Time, nil)
  • created_at_lte (Time, nil)
  • cursor (String, nil) —

    Cursor for pagination. This can be populated by the next_cursor value returned

  • limit (Integer) —

    The number of items to fetch. Defaults to 20.

  • status (Symbol, Orb::Models::PlanListParams::Status) —

    The plan status to filter to ('active', 'archived', or 'draft').

  • request_options (Orb::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
 
# File 'lib/orb/resources/plans.rb', line 127

def list(params = {})
  parsed, options = Orb::PlanListParams.dump_request(params)
  query = Orb::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :get,
    path: "plans",
    query: query.transform_keys(
      created_at_gt: "created_at[gt]",
      created_at_gte: "created_at[gte]",
      created_at_lt: "created_at[lt]",
      created_at_lte: "created_at[lte]"
    ),
    page: Orb::Internal::Page,
    model: Orb::Plan,
    options: options
  )
end

#update(plan_id, description: nil, external_plan_id: nil, metadata: nil, request_options: {}) ⇒ Orb::Models::Plan

Some parameter documentations has been truncated, see Models::PlanUpdateParams for more details.

This endpoint can be used to update the external_plan_id, description, and metadata of an existing plan.

Other fields on a plan are currently immutable.

Parameters:

  • plan_id (String)
  • description (String, nil) —

    An optional user-defined description of the plan.

  • external_plan_id (String, nil) —

    An optional user-defined ID for this plan resource, used throughout the system a

  • metadata (Hash{Symbol=>String, nil}, nil) —

    User-specified key/value pairs for the resource. Individual keys can be removed

  • request_options (Orb::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



86
87
88
89
90
91
92
93
94
95
 
# File 'lib/orb/resources/plans.rb', line 86

def update(plan_id, params = {})
  parsed, options = Orb::PlanUpdateParams.dump_request(params)
  @client.request(
    method: :put,
    path: ["plans/%1$s", plan_id],
    body: parsed,
    model: Orb::Plan,
    options: options
  )
end