Class: MetronomeSDK::Resources::V1::Packages

Inherits:
Object
  • Object
show all
Defined in:
lib/metronome_sdk/resources/v1/packages.rb

Instance Method Summary collapse

Constructor Details

#initialize(client:) ⇒ Packages

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

Parameters:



263
264
265
 
# File 'lib/metronome_sdk/resources/v1/packages.rb', line 263

def initialize(client:)
  @client = client
end

Instance Method Details

#archive(package_id:, request_options: {}) ⇒ MetronomeSDK::Models::V1::PackageArchiveResponse

Archive a package. Archived packages cannot be used to create new contracts. However, existing contracts associated with the package will continue to function as normal. Once you archive a package, you can still retrieve it in the UI and API, but you cannot unarchive it.

Parameters:

Returns:

See Also:



193
194
195
196
197
198
199
200
201
202
 
# File 'lib/metronome_sdk/resources/v1/packages.rb', line 193

def archive(params)
  parsed, options = MetronomeSDK::V1::PackageArchiveParams.dump_request(params)
  @client.request(
    method: :post,
    path: "v1/packages/archive",
    body: parsed,
    model: MetronomeSDK::Models::V1::PackageArchiveResponse,
    options: options
  )
end

#create(name:, aliases: nil, billing_anchor_date: nil, billing_provider: nil, commits: nil, contract_name: nil, credits: nil, delivery_method: nil, duration: nil, multiplier_override_prioritization: nil, net_payment_terms_days: nil, overrides: nil, prepaid_balance_threshold_configuration: nil, rate_card_alias: nil, rate_card_id: nil, recurring_commits: nil, recurring_credits: nil, scheduled_charges: nil, scheduled_charges_on_usage_invoices: nil, spend_threshold_configuration: nil, subscriptions: nil, uniqueness_key: nil, usage_statement_schedule: nil, request_options: {}) ⇒ MetronomeSDK::Models::V1::PackageCreateResponse

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

Create a package that defines a set of reusable, time-relative contract terms that can be used across cohorts of customers. Packages provide an abstraction layer on top of rate cards to provide an easy way to provision customers with standard pricing.

### **Use this endpoint to:**

  • Model standard pay-as-you-go pricing packages that can be easily reused across customers

  • Define standardized contract terms and discounting for sales-led motions

  • Set aliases for the package to facilitate easy package transition. Aliases are human-readable names that you can use in the place of the id of the package when provisioning a customer’s contract. By using an alias, you can easily create a contract and provision a customer by choosing the “Starter Plan”package, without storing the package ID in your internal systems. This is helpful when launching terms for a package, as you can create a new package with the “Starter Plan” alias scheduled to be assigned without updating your provisioning code.

### Key input fields:

  • ‘starting_at_offset`: Starting date relative to contract start. Generates the `starting_at` date when a contract is provisioned using a package.

  • ‘duration`: Duration starting from `starting_at_offset`. Generates the `ending_before` date when a contract is provisioned using a package.

  • ‘date_offset`: Date relative to contract start. Used for point-in-time dates without a duration.

  • ‘aliases`: Human-readable name to use when provisioning contracts with a package.

### Usage guidelines:

  • Use packages for standard self-serve use cases where customers have consistent terms. For customers with negotiated custom contract terms, use the ‘createContract` endpoint for maximum flexibility.

  • Billing provider configuration can be set when creating a package by using ‘billing_provider` and `delivery_method`. To provision a customer successfully with a package, the customer must have one and only one billing provider configuration that matches the billing provider configuration set on the package.

  • A package alias can only be used by one package at a time. If you create a new package with an alias that is already in use by another package, the original package’s alias schedule will be updated. The alias will reference the package to which it was most recently assigned.

  • Terms can only be specified using times relative to the contract start date. Supported granularities are: ‘days`, `weeks`, `months`, `years`

  • Packages cannot be edited once created. Use the rate card to easily add new rates across all of your customers or make direct edits to a contract after provisioning with a package. Edited contracts will still be associated with the package used during provisioning.

Parameters:

Returns:

See Also:



114
115
116
117
118
119
120
121
122
123
 
# File 'lib/metronome_sdk/resources/v1/packages.rb', line 114

def create(params)
  parsed, options = MetronomeSDK::V1::PackageCreateParams.dump_request(params)
  @client.request(
    method: :post,
    path: "v1/packages/create",
    body: parsed,
    model: MetronomeSDK::Models::V1::PackageCreateResponse,
    options: options
  )
end

#list(limit: nil, next_page: nil, archive_filter: nil, request_options: {}) ⇒ MetronomeSDK::Internal::CursorPage<MetronomeSDK::Models::V1::PackageListResponse>

Lists all packages with details including name, aliases, duration, and terms. To view contracts on a specific package, use the ‘listContractsOnPackage` endpoint.

Parameters:

  • limit (Integer) —

    Query param: The maximum number of packages to return. Defaults to 10.

  • next_page (String) —

    Query param: Cursor that indicates where the next page of results should start.

  • archive_filter (Symbol, MetronomeSDK::Models::V1::PackageListParams::ArchiveFilter) —

    Body param: Filter packages by archived status. Defaults to NOT_ARCHIVED.

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

Returns:

See Also:



164
165
166
167
168
169
170
171
172
173
174
175
176
177
 
# File 'lib/metronome_sdk/resources/v1/packages.rb', line 164

def list(params = {})
  query_params = [:limit, :next_page]
  parsed, options = MetronomeSDK::V1::PackageListParams.dump_request(params)
  query = MetronomeSDK::Internal::Util.encode_query_params(parsed.slice(*query_params))
  @client.request(
    method: :post,
    path: "v1/packages/list",
    query: query,
    body: parsed.except(*query_params),
    page: MetronomeSDK::Internal::CursorPage,
    model: MetronomeSDK::Models::V1::PackageListResponse,
    options: options
  )
end

#list_contracts_on_package(package_id:, limit: nil, next_page: nil, covering_date: nil, include_archived: nil, starting_at: nil, request_options: {}) ⇒ MetronomeSDK::Internal::CursorPage<MetronomeSDK::Models::V1::PackageListContractsOnPackageResponse>

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

For a given package, returns all contract IDs and customer IDs associated with the package over a specific time period.

### Use this endpoint to:

  • Understand which customers are provisioned on a package at any given time for internal cohort management

  • Manage customer migrations to a new package. For example, to migrate all active customers to a new package, call this endpoint, end contracts, and provision customers on a new package.

### **Usage guidelines:**

Use the **‘starting_at`**, **`covering_date`**, and **`include_archived`** parameters to filter the list of returned contracts. For example, to list only currently active contracts, pass **`covering_date`** equal to the current time.

Parameters:

  • package_id (String) —

    Body param

  • limit (Integer) —

    Query param: Max number of results that should be returned

  • next_page (String) —

    Query param: Cursor that indicates where the next page of results should start.

  • covering_date (Time) —

    Body param: Optional RFC 3339 timestamp. Only include contracts active on the pr

  • include_archived (Boolean) —

    Body param: Default false. Determines whether to include archived contracts in t

  • starting_at (Time) —

    Body param: Optional RFC 3339 timestamp. Only include contracts that started on

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

Returns:

See Also:



245
246
247
248
249
250
251
252
253
254
255
256
257
258
 
# File 'lib/metronome_sdk/resources/v1/packages.rb', line 245

def list_contracts_on_package(params)
  query_params = [:limit, :next_page]
  parsed, options = MetronomeSDK::V1::PackageListContractsOnPackageParams.dump_request(params)
  query = MetronomeSDK::Internal::Util.encode_query_params(parsed.slice(*query_params))
  @client.request(
    method: :post,
    path: "v1/packages/listContractsOnPackage",
    query: query,
    body: parsed.except(*query_params),
    page: MetronomeSDK::Internal::CursorPage,
    model: MetronomeSDK::Models::V1::PackageListContractsOnPackageResponse,
    options: options
  )
end

#retrieve(package_id:, request_options: {}) ⇒ MetronomeSDK::Models::V1::PackageRetrieveResponse

Gets the details for a specific package, including name, aliases, duration, and terms. Use this endpoint to understand a package’s alias schedule, or display a specific package’s details to end customers.

Parameters:

Returns:

See Also:



137
138
139
140
141
142
143
144
145
146
 
# File 'lib/metronome_sdk/resources/v1/packages.rb', line 137

def retrieve(params)
  parsed, options = MetronomeSDK::V1::PackageRetrieveParams.dump_request(params)
  @client.request(
    method: :post,
    path: "v1/packages/get",
    body: parsed,
    model: MetronomeSDK::Models::V1::PackageRetrieveResponse,
    options: options
  )
end