Class: ApiReference::SubscriptionApi

Inherits:
BaseApi
  • Object
show all
Defined in:
lib/api_reference/apis/subscription_api.rb

Overview

SubscriptionApi

Constant Summary

Constants inherited from BaseApi

BaseApi::GLOBAL_ERRORS

Instance Attribute Summary

Attributes inherited from BaseApi

#config, #http_call_back

Instance Method Summary collapse

Methods inherited from BaseApi

#initialize, #new_parameter, #new_request_builder, #new_response_handler, user_agent, user_agent_parameters

Constructor Details

This class inherits a constructor from ApiReference::BaseApi

Instance Method Details

#cancel_subscription(subscription_id, body) ⇒ ApiResponse

This endpoint can be used to cancel an existing subscription. It returns the serialized subscription object with an end_date parameter that signifies when the subscription will transition to an ended state. The body parameter cancel_option determines the cancellation behavior. Orb supports three cancellation options:

  • end_of_subscription_term: stops the subscription from auto-renewing. Subscriptions that have been cancelled with this option can still incur charges for the remainder of their term:

    - Issuing this cancellation request for a monthly subscription will

    keep the subscription active until the start of the subsequent month, and potentially issue an invoice for any usage charges incurred in the intervening period.

    • Issuing this cancellation request for a quarterly subscription will keep the subscription active until the end of the quarter and potentially issue an invoice for any usage charges incurred in the intervening period.
    • Issuing this cancellation request for a yearly subscription will keep the subscription active for the full year. For example, a yearly subscription starting on 2021-11-01 and cancelled on 2021-12-08 will remain active until 2022-11-01 and potentially issue charges in the intervening months for any recurring monthly usage charges in its plan.
    • Note: If a subscription's plan contains prices with difference cadences, the end of term date will be determined by the largest cadence value. For example, cancelling end of term for a subscription with a quarterly fixed fee with a monthly usage fee will result in the subscription ending at the end of the quarter.

  • immediate: ends the subscription immediately, setting the end_date to the current time:

    - Subscriptions that have been cancelled with this option will be

    invoiced immediately. This invoice will include any usage fees incurred in the billing period up to the cancellation, along with any prorated recurring fees for the billing period, if applicable.

    • Note: If the subscription has a recurring fee that was paid in-advance, the prorated amount for the remaining time period will be added to the customer's balance upon immediate cancellation. However, if the customer is ineligible to use the customer balance, the subscription cannot be cancelled immediately.

  • requested_date: ends the subscription on a specified date, which requires a cancellation_date to be passed in. If no timezone is provided, the customer's timezone is used. For example, a subscription starting on January 1st with a monthly price can be set to be cancelled on the first of any month after January 1st (e.g. March 1st, April 1st, May 1st). A subscription with multiple prices with different cadences defines the "term" to be the highest cadence of the prices. Upcoming subscriptions are only eligible for immediate cancellation, which will set the end_date equal to the start_date upon cancellation.

Backdated cancellations

Orb allows you to cancel a subscription in the past as long as there are no paid invoices between the requested_date and the current time. If the cancellation is after the latest issued invoice, Orb will generate a balance refund for the current period. If the cancellation is before the most recently issued invoice, Orb will void the intervening invoice and generate a new one based on the new dates for the subscription. See the section on cancellation behaviors . here description here

Parameters:

  • subscription_id (String) —

    Required parameter: TODO: type description

  • body (CancelSubscriptionParams) —

    Required parameter: TODO: type

Returns:

  • (ApiResponse) —

    Complete http response with raw body and status code.



541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
 
# File 'lib/api_reference/apis/subscription_api.rb', line 541

def cancel_subscription(subscription_id,
                        body)
  @api_call
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/subscriptions/{subscription_id}/cancel',
                                 Server::DEFAULT)
               .template_param(new_parameter(subscription_id, key: 'subscription_id')
                                .is_required(true)
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .body_param(new_parameter(body)
                            .is_required(true))
               .header_param(new_parameter('application/json', key: 'accept'))
               .body_serializer(proc do |param| param.to_json unless param.nil? end)
               .auth(Single.new('APIKeyAuth')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(MutatedSubscription.method(:from_hash))
                .is_api_response(true)
                .local_error('400',
                             'Bad Request',
                             APIException)
                .local_error('401',
                             'Unauthorized',
                             AuthorizationErrorException)
                .local_error('404',
                             'Not Found',
                             APIException)
                .local_error('409',
                             'Conflict',
                             IdempotencyRequestMismatchException)
                .local_error('413',
                             'Content Too Large',
                             APIException)
                .local_error('429',
                             'Too Many Requests',
                             TooManyRequestsException)
                .local_error('500',
                             'Internal Server Error',
                             ServerErrorException))
    .execute
end

#create_subscription(body) ⇒ ApiResponse

A subscription represents the purchase of a plan by a customer. The customer is identified by either the customer_id or the external_customer_id, and exactly one of these fields must be provided. By default, subscriptions begin on the day that they're created and renew automatically for each billing cycle at the cadence that's configured in the plan definition. The default configuration for subscriptions in Orb is In-advance billing and Beginning of month alignment (see Subscription for more details). In order to change the alignment behavior, Orb also supports billing subscriptions on the day of the month they are created. If align_billing_with_subscription_start_date = true is specified, subscriptions have billing cycles that are aligned with their start_date. For example, a subscription that begins on January 15th will have a billing cycle from January 15th to February 15th. Every subsequent billing cycle will continue to start and invoice on the 15th. If the "day" value is greater than the number of days in the month, the next billing cycle will start at the end of the month. For example, if the start_date is January 31st, the next billing cycle will start on February 28th. If a customer was created with a currency, Orb only allows subscribing the customer to a plan with a matching invoicing_currency. If the customer does not have a currency set, on subscription creation, we set the customer's currency to be the invoicing_currency of the plan.

Customize your customer's subscriptions

Prices and adjustments in a plan can be added, removed, or replaced for the subscription being created. This is useful when a customer has prices that differ from the default prices for a specific plan. This feature is only available for accounts that have migrated to Subscription Overrides Version 2. You can find your Subscription Overrides Version at the bottom of your Plans page

Adding Prices

To add prices, provide a list of objects with the key add_prices. An object in the list must specify an existing add-on price with a price_id or external_price_id field, or create a new add-on price by including an object with the key price, identical to what would be used in the request body for the create price endpoint. See the Price resource for the specification of different price model configurations possible in this object. If the plan has phases, each object in the list must include a number with plan_phase_order key to indicate which phase the price should be added to. An object in the list can specify an optional start_date and optional end_date. This is equivalent to creating a price interval with the add/edit price intervals endpoint. If unspecified, the start or end date of the phase or subscription will be used. An object in the list can specify an optional minimum_amount, maximum_amount, or discounts. This will create adjustments which apply only to this price. Additionally, an object in the list can specify an optional reference_id. This ID can be used to reference this price when adding an adjustment in the same API call. However the ID is transient and cannot be used to refer to the price in future API calls.

Removing Prices

To remove prices, provide a list of objects with the key remove_prices. An object in the list must specify a plan price with either a price_id or external_price_id field.

Replacing Prices

To replace prices, provide a list of objects with the key replace_prices. An object in the list must specify a plan price to replace with the replaces_price_id key, and it must specify a price to replace it with by either referencing an existing add-on price with a price_id or external_price_id field, or by creating a new add-on price by including an object with the key price, identical to what would be used in the request body for the create price endpoint. See the Price resource for the specification of different price model configurations possible in this object. For fixed fees, an object in the list can supply a fixed_price_quantity instead of a price, price_id, or external_price_id field. This will update only the quantity for the price, similar to the Update price quantity endpoint. The replacement price will have the same phase, if applicable, and the same start and end dates as the price it replaces. An object in the list can specify an optional minimum_amount, maximum_amount, or discounts. This will create adjustments which apply only to this price. Additionally, an object in the list can specify an optional reference_id. This ID can be used to reference the replacement price when adding an adjustment in the same API call. However the ID is transient and cannot be used to refer to the price in future API calls.

Adding adjustments

To add adjustments, provide a list of objects with the key add_adjustments. An object in the list must include an object with the key adjustment, identical to the adjustment object in the add/edit price intervals endpoint. If the plan has phases, each object in the list must include a number with plan_phase_order key to indicate which phase the adjustment should be added to. An object in the list can specify an optional start_date and optional end_date. If unspecified, the start or end date of the phase or subscription will be used.

Removing adjustments

To remove adjustments, provide a list of objects with the key remove_adjustments. An object in the list must include a key, adjustment_id, with the ID of the adjustment to be removed.

Replacing adjustments

To replace adjustments, provide a list of objects with the key replace_adjustments. An object in the list must specify a plan adjustment to replace with the replaces_adjustment_id key, and it must specify an adjustment to replace it with by including an object with the key adjustment, identical to the adjustment object in the add/edit price intervals endpoint. The replacement adjustment will have the same phase, if applicable, and the same start and end dates as the adjustment it replaces.

Price overrides (DEPRECATED)

Price overrides are being phased out in favor adding/removing/replacing prices. (See [Customize your customer's subscriptions](/api-reference/subscription/create-subscription)) Price overrides are used to update some or all prices in a plan for the specific subscription being created. This is useful when a new customer has negotiated a rate that is unique to the customer. To override prices, provide a list of objects with the key `price_overrides`. The price object in the list of overrides is expected to contain the existing price id, the `model_type` and configuration. (See the [Price resource](/product-catalog/price-configuration) for the specification of different price model configurations.) The numerical values can be updated, but the billable metric, cadence, type, and name of a price can not be overridden. ### Maximums and Minimums Minimums and maximums, much like price overrides, can be useful when a new customer has negotiated a new or different minimum or maximum spend cap than the default for a given price. If one exists for a price and null is provided for the minimum/maximum override on creation, then there will be no minimum/maximum on the new subscription. If no value is provided, then the default price maximum or minimum is used. To add a minimum for a specific price, add `minimum_amount` to the specific price in the `price_overrides` object. To add a maximum for a specific price, add `maximum_amount` to the specific price in the `price_overrides` object. ### Minimum override example Price minimum override example: ```json { ... "id": "price_id", "model_type": "unit", "unit_config": { "unit_amount": "0.50" }, "minimum_amount": "100.00" ... } ``` Removing an existing minimum example ```json { ... "id": "price_id", "model_type": "unit", "unit_config": { "unit_amount": "0.50" }, "minimum_amount": null ... } ``` ### Discounts Discounts, like price overrides, can be useful when a new customer has negotiated a new or different discount than the default for a price. If a discount exists for a price and a null discount is provided on creation, then there will be no discount on the new subscription. To add a discount for a specific price, add `discount` to the price in the `price_overrides` object. Discount should be a dictionary of the format: ```ts { "discount_type": "amount" | "percentage" | "usage", "amount_discount": string, "percentage_discount": string, "usage_discount": string } ``` where either `amount_discount`, `percentage_discount`, or `usage_discount` is provided. Price discount example ```json { ... "id": "price_id", "model_type": "unit", "unit_config": { "unit_amount": "0.50" }, "discount": "amount", "amount_discount": "175", } ``` Removing an existing discount example ```json { "customer_id": "customer_id", "plan_id": "plan_id", "discount": null, "price_overrides": [ ... ] ... } ``` ## Threshold Billing Orb supports invoicing for a subscription when a preconfigured usage threshold is hit. To enable threshold billing, pass in an `invoicing_threshold`, which is specified in the subscription's invoicing currency, when creating a subscription. E.g. pass in `10.00` to issue an invoice when usage amounts hit \$10.00 for a subscription that invoices in USD. ## Limits By default, Orb limits the number of subscriptions per customer to 100. here

Parameters:

Returns:

  • (ApiResponse) —

    Complete http response with raw body and status code.



334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
 
# File 'lib/api_reference/apis/subscription_api.rb', line 334

def create_subscription(body)
  @api_call
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/subscriptions',
                                 Server::DEFAULT)
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .body_param(new_parameter(body)
                            .is_required(true))
               .header_param(new_parameter('application/json', key: 'accept'))
               .body_serializer(proc do |param| param.to_json unless param.nil? end)
               .auth(Single.new('APIKeyAuth')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(MutatedSubscription.method(:from_hash))
                .is_api_response(true)
                .local_error('400',
                             'Bad Request',
                             APIException)
                .local_error('401',
                             'Unauthorized',
                             AuthorizationErrorException)
                .local_error('404',
                             'Not Found',
                             APIException)
                .local_error('409',
                             'Conflict',
                             IdempotencyRequestMismatchException)
                .local_error('413',
                             'Content Too Large',
                             APIException)
                .local_error('429',
                             'Too Many Requests',
                             TooManyRequestsException)
                .local_error('500',
                             'Internal Server Error',
                             ServerErrorException))
    .execute
end

#fetch_subscription(subscription_id) ⇒ ApiResponse

This endpoint is used to fetch a Subscription given an identifier. here

Parameters:

  • subscription_id (String) —

    Required parameter: TODO: type description

Returns:

  • (ApiResponse) —

    Complete http response with raw body and status code.



378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
 
# File 'lib/api_reference/apis/subscription_api.rb', line 378

def fetch_subscription(subscription_id)
  @api_call
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/subscriptions/{subscription_id}',
                                 Server::DEFAULT)
               .template_param(new_parameter(subscription_id, key: 'subscription_id')
                                .is_required(true)
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'accept'))
               .auth(Single.new('APIKeyAuth')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(Subscription.method(:from_hash))
                .is_api_response(true)
                .local_error('400',
                             'Bad Request',
                             APIException)
                .local_error('401',
                             'Unauthorized',
                             AuthorizationErrorException)
                .local_error('404',
                             'Not Found',
                             APIException)
                .local_error('409',
                             'Conflict',
                             IdempotencyRequestMismatchException)
                .local_error('413',
                             'Content Too Large',
                             APIException)
                .local_error('429',
                             'Too Many Requests',
                             TooManyRequestsException)
                .local_error('500',
                             'Internal Server Error',
                             ServerErrorException))
    .execute
end

#fetch_subscription_costs(subscription_id, timeframe_start: nil, timeframe_end: nil, view_mode: nil, currency: nil) ⇒ ApiResponse

This endpoint is used to fetch a day-by-day snapshot of a subscription's costs in Orb, calculated by applying pricing information to the underlying usage (see the subscription usage endpoint to fetch usage per metric, in usage units rather than a currency). The semantics of this endpoint exactly mirror those of fetching a customer's costs. Use this endpoint to limit your analysis of costs to a specific subscription for the customer (e.g. to de-aggregate costs when a customer's subscription has started and stopped on the same day). here description here here

Parameters:

  • subscription_id (String) —

    Required parameter: TODO: type description

  • timeframe_start (DateTime) (defaults to: nil) —

    Optional parameter: TODO: type

  • timeframe_end (DateTime) (defaults to: nil) —

    Optional parameter: TODO: type description

  • view_mode (ViewMode) (defaults to: nil) —

    Optional parameter: Example:

  • currency (String) (defaults to: nil) —

    Optional parameter: TODO: type description here

Returns:

  • (ApiResponse) —

    Complete http response with raw body and status code.



604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
 
# File 'lib/api_reference/apis/subscription_api.rb', line 604

def fetch_subscription_costs(subscription_id,
                             timeframe_start: nil,
                             timeframe_end: nil,
                             view_mode: nil,
                             currency: nil)
  @api_call
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/subscriptions/{subscription_id}/costs',
                                 Server::DEFAULT)
               .template_param(new_parameter(subscription_id, key: 'subscription_id')
                                .is_required(true)
                                .should_encode(true))
               .query_param(new_parameter(timeframe_start, key: 'timeframe_start'))
               .query_param(new_parameter(timeframe_end, key: 'timeframe_end'))
               .query_param(new_parameter(view_mode, key: 'view_mode'))
               .query_param(new_parameter(currency, key: 'currency'))
               .header_param(new_parameter('application/json', key: 'accept'))
               .auth(Single.new('APIKeyAuth')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(SubscriptionCosts.method(:from_hash))
                .is_api_response(true)
                .local_error('400',
                             'Bad Request',
                             APIException)
                .local_error('401',
                             'Unauthorized',
                             AuthorizationErrorException)
                .local_error('404',
                             'Not Found',
                             APIException)
                .local_error('409',
                             'Conflict',
                             IdempotencyRequestMismatchException)
                .local_error('413',
                             'Content Too Large',
                             APIException)
                .local_error('429',
                             'Too Many Requests',
                             TooManyRequestsException)
                .local_error('500',
                             'Internal Server Error',
                             ServerErrorException))
    .execute
end

#fetch_subscription_schedule(subscription_id, limit: 20, cursor: nil, start_date_gte: nil, start_date_gt: nil, start_date_lt: nil, start_date_lte: nil) ⇒ ApiResponse

This endpoint returns a paginated list of all plans associated with a subscription along with their start and end dates. This list contains the subscription's initial plan along with past and future plan changes. here description here here here description here

Parameters:

  • subscription_id (String) —

    Required parameter: TODO: type description

  • limit (Integer) (defaults to: 20) —

    Optional parameter: Example:20

  • cursor (String) (defaults to: nil) —

    Optional parameter: TODO: type description here

  • start_date_gte (DateTime) (defaults to: nil) —

    Optional parameter: TODO: type

  • start_date_gt (DateTime) (defaults to: nil) —

    Optional parameter: TODO: type description

  • start_date_lt (DateTime) (defaults to: nil) —

    Optional parameter: TODO: type description

  • start_date_lte (DateTime) (defaults to: nil) —

    Optional parameter: TODO: type

Returns:

  • (ApiResponse) —

    Complete http response with raw body and status code.



717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
 
# File 'lib/api_reference/apis/subscription_api.rb', line 717

def fetch_subscription_schedule(subscription_id,
                                limit: 20,
                                cursor: nil,
                                start_date_gte: nil,
                                start_date_gt: nil,
                                start_date_lt: nil,
                                start_date_lte: nil)
  @api_call
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/subscriptions/{subscription_id}/schedule',
                                 Server::DEFAULT)
               .template_param(new_parameter(subscription_id, key: 'subscription_id')
                                .is_required(true)
                                .should_encode(true))
               .query_param(new_parameter(limit, key: 'limit'))
               .query_param(new_parameter(cursor, key: 'cursor'))
               .query_param(new_parameter(start_date_gte, key: 'start_date[gte]'))
               .query_param(new_parameter(start_date_gt, key: 'start_date[gt]'))
               .query_param(new_parameter(start_date_lt, key: 'start_date[lt]'))
               .query_param(new_parameter(start_date_lte, key: 'start_date[lte]'))
               .header_param(new_parameter('application/json', key: 'accept'))
               .auth(Single.new('APIKeyAuth')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(SubscriptionScheduleItems.method(:from_hash))
                .is_api_response(true)
                .local_error('400',
                             'Bad Request',
                             APIException)
                .local_error('401',
                             'Unauthorized',
                             AuthorizationErrorException)
                .local_error('404',
                             'Not Found',
                             APIException)
                .local_error('409',
                             'Conflict',
                             IdempotencyRequestMismatchException)
                .local_error('413',
                             'Content Too Large',
                             APIException)
                .local_error('429',
                             'Too Many Requests',
                             TooManyRequestsException)
                .local_error('500',
                             'Internal Server Error',
                             ServerErrorException))
    .execute
end

#fetch_subscription_usage(subscription_id, granularity: Granularity::DAY, timeframe_start: nil, timeframe_end: nil, billable_metric_id: nil, group_by: nil, view_mode: nil, first_dimension_key: nil, first_dimension_value: nil, second_dimension_key: nil, second_dimension_value: nil) ⇒ ApiResponse

This endpoint is used to fetch a subscription's usage in Orb. Especially when combined with optional query parameters, this endpoint is a powerful way to build visualizations on top of Orb's event data and metrics. With no query parameters specified, this endpoint returns usage for the subscription's current billing period across each billable metric that participates in the subscription. Usage quantities returned are the result of evaluating the metric definition for the entirety of the customer's billing period.

Default response shape

Orb returns a data array with an object corresponding to each billable metric. Nested within this object is a usage array which has a quantity value and a corresponding timeframe_start and timeframe_end. The quantity value represents the calculated usage value for the billable metric over the specified timeframe (inclusive of the timeframe_start timestamp and exclusive of the timeframe_end timestamp). Orb will include every window in the response starting from the beginning of the billing period, even when there were no events (and therefore no usage) in the window. This increases the size of the response but prevents the caller from filling in gaps and handling cumbersome time-based logic. The query parameters in this endpoint serve to override this behavior and provide some key functionality, as listed below. Note that this functionality can also be used in conjunction with each other, e.g. to display grouped usage on a custom timeframe.

Custom timeframe

In order to view usage for a custom timeframe rather than the current billing period, specify a timeframe_start and timeframe_end. This will calculate quantities for usage incurred between timeframe_start (inclusive) and timeframe_end (exclusive), i.e. [timeframe_start, timeframe_end). Note:

  • These timestamps must be specified in ISO 8601 format and UTC timezone, e.g. 2022-02-01T05:00:00Z.
  • Both parameters must be specified if either is specified.

Grouping by custom attributes

In order to view a single metric grouped by a specific attribute that each event is tagged with (e.g. cluster), you must additionally specify a billable_metric_id and a group_by key. The group_by key denotes the event property on which to group. When returning grouped usage, only usage for billable_metric_id is returned, and a separate object in the data array is returned for each value of the group_by key present in your events. The quantity value is the result of evaluating the billable metric for events filtered to a single value of the group_by key. Orb expects that events that match the billable metric will contain values in the properties dictionary that correspond to the group_by key specified. By default, Orb will not return a null group (i.e. events that match the metric but do not have the key set). Currently, it is only possible to view usage grouped by a single attribute at a time. When viewing grouped usage, Orb uses pagination to limit the response size to 1000 groups by default. If there are more groups for a given subscription, pagination metadata in the response can be used to fetch all of the data. The following example shows usage for an "API Requests" billable metric grouped by region. Note the extra metric_group dictionary in the response, which provides metadata about the group:

{
    "data": [
        {
            "usage": [
                {
                    "quantity": 0.19291,
                    "timeframe_start": "2021-10-01T07:00:00Z",
                    "timeframe_end": "2021-10-02T07:00:00Z",
                },
                ...
            ],
            "metric_group": {
                "property_key": "region",
                "property_value": "asia/pacific"
            },
            "billable_metric": {
                "id": "Fe9pbpMk86xpwdGB",
                "name": "API Requests"
            },
            "view_mode": "periodic"
        },
        ...
    ]
}

Windowed usage

The granularity parameter can be used to window the usage quantity value into periods. When not specified, usage is returned for the entirety of the time range. When granularity = day is specified with a timeframe longer than a day, Orb will return a quantity value for each full day between timeframe_start and timeframe_end. Note that the days are demarcated by the customer's local midnight. For example, with timeframe_start = 2022-02-01T05:00:00Z, `timeframe_end

2022-02-04T01:00:00Zandgranularity=day`,

the following windows will be returned for a customer in the America/Los_Angeles timezone since local midnight is 08:00 UTC:

  • [2022-02-01T05:00:00Z, 2022-02-01T08:00:00Z)
  • [2022-02-01T08:00:00, 2022-02-02T08:00:00Z)
  • [2022-02-02T08:00:00, 2022-02-03T08:00:00Z)
  • [2022-02-03T08:00:00, 2022-02-04T01:00:00Z)
{
    "data": [
        {
            "billable_metric": {
                "id": "Q8w89wjTtBdejXKsm",
                "name": "API Requests"
            },
            "usage": [
                {
                    "quantity": 0,
                    "timeframe_end": "2022-02-01T08:00:00+00:00",
                    "timeframe_start": "2022-02-01T05:00:00+00:00"
                },
                {
                    "quantity": 0,
                    "timeframe_end": "2022-02-02T08:00:00+00:00",
                    "timeframe_start": "2022-02-01T08:00:00+00:00"
                },
                {
                    "quantity": 0,
                    "timeframe_end": "2022-02-03T08:00:00+00:00",
                    "timeframe_start": "2022-02-02T08:00:00+00:00"
                },
                {
                    "quantity": 0,
                    "timeframe_end": "2022-02-04T01:00:00+00:00",
                    "timeframe_start": "2022-02-03T08:00:00+00:00"
                }
            ],
            "view_mode": "periodic"
        },
        ...
    ]
}

Decomposable vs. non-decomposable metrics

Billable metrics fall into one of two categories: decomposable and non-decomposable. A decomposable billable metric, such as a sum or a count, can be displayed and aggregated across arbitrary timescales. On the other hand, a non-decomposable metric is not meaningful when only a slice of the billing window is considered. As an example, if we have a billable metric that's defined to count unique users, displaying a graph of unique users for each day is not representative of the billable metric value over the month (days could have an overlapping set of 'unique' users). Instead, what's useful for any given day is the number of unique users in the billing period so far, which are the cumulative unique users. Accordingly, this endpoint returns treats these two types of metrics differently when group_by is specified:

  • Decomposable metrics can be grouped by any event property.
  • Non-decomposable metrics can only be grouped by the corresponding price's invoice grouping key. If no invoice grouping key is present, the metric does not support group_by.

Matrix prices

When a billable metric is attached to a price that uses matrix pricing, it's important to view usage grouped by those matrix dimensions. In this case, use the query parameters first_dimension_key, first_dimension_value and second_dimension_key, second_dimension_value while filtering to a specific billable_metric_id. For example, if your compute metric has a separate unit price (i.e. a matrix pricing model) per region and provider, your request might provide the following parameters:

  • first_dimension_key: region
  • first_dimension_value: us-east-1
  • second_dimension_key: provider
  • second_dimension_value: aws here description here here description here description here description here description here description here

Parameters:

  • subscription_id (String) —

    Required parameter: TODO: type description

  • granularity (Granularity) (defaults to: Granularity::DAY) —

    Optional parameter: Example:day

  • timeframe_start (DateTime) (defaults to: nil) —

    Optional parameter: TODO: type

  • timeframe_end (DateTime) (defaults to: nil) —

    Optional parameter: TODO: type description

  • billable_metric_id (String) (defaults to: nil) —

    Optional parameter: TODO: type

  • group_by (String) (defaults to: nil) —

    Optional parameter: TODO: type description here

  • view_mode (ViewMode) (defaults to: nil) —

    Optional parameter: Example:

  • first_dimension_key (String) (defaults to: nil) —

    Optional parameter: TODO: type

  • first_dimension_value (String) (defaults to: nil) —

    Optional parameter: TODO: type

  • second_dimension_key (String) (defaults to: nil) —

    Optional parameter: TODO: type

  • second_dimension_value (String) (defaults to: nil) —

    Optional parameter: TODO: type

Returns:

  • (ApiResponse) —

    Complete http response with raw body and status code.



1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
 
# File 'lib/api_reference/apis/subscription_api.rb', line 1513

def fetch_subscription_usage(subscription_id,
                             granularity: Granularity::DAY,
                             timeframe_start: nil,
                             timeframe_end: nil,
                             billable_metric_id: nil,
                             group_by: nil,
                             view_mode: nil,
                             first_dimension_key: nil,
                             first_dimension_value: nil,
                             second_dimension_key: nil,
                             second_dimension_value: nil)
  @api_call
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/subscriptions/{subscription_id}/usage',
                                 Server::DEFAULT)
               .template_param(new_parameter(subscription_id, key: 'subscription_id')
                                .is_required(true)
                                .should_encode(true))
               .query_param(new_parameter(granularity, key: 'granularity'))
               .query_param(new_parameter(timeframe_start, key: 'timeframe_start'))
               .query_param(new_parameter(timeframe_end, key: 'timeframe_end'))
               .query_param(new_parameter(billable_metric_id, key: 'billable_metric_id'))
               .query_param(new_parameter(group_by, key: 'group_by'))
               .query_param(new_parameter(view_mode, key: 'view_mode'))
               .query_param(new_parameter(first_dimension_key, key: 'first_dimension_key'))
               .query_param(new_parameter(first_dimension_value, key: 'first_dimension_value'))
               .query_param(new_parameter(second_dimension_key, key: 'second_dimension_key'))
               .query_param(new_parameter(second_dimension_value, key: 'second_dimension_value'))
               .header_param(new_parameter('application/json', key: 'accept'))
               .auth(Single.new('APIKeyAuth')))
    .response(new_response_handler
                .deserializer(proc do |response, should_symbolize|
                  APIHelper.deserialize_union_type(
                    UnionTypeLookUp.get(:SubscriptionUsage),
                    response, should_symbolize, true
                  )
                end)
                .is_api_response(true)
                .local_error('400',
                             'Bad Request',
                             APIException)
                .local_error('401',
                             'Unauthorized',
                             AuthorizationErrorException)
                .local_error('404',
                             'Not Found',
                             APIException)
                .local_error('409',
                             'Conflict',
                             IdempotencyRequestMismatchException)
                .local_error('413',
                             'Content Too Large',
                             APIException)
                .local_error('429',
                             'Too Many Requests',
                             TooManyRequestsException)
                .local_error('500',
                             'Internal Server Error',
                             ServerErrorException))
    .execute
end

#list_subscriptions(limit: 20, cursor: nil, customer_id: nil, external_customer_id: nil, plan_id: nil, external_plan_id: nil, status: nil, created_at_gte: nil, created_at_gt: nil, created_at_lt: nil, created_at_lte: nil) ⇒ ApiResponse

This endpoint returns a list of all subscriptions for an account as a paginated list, ordered starting from the most recently created subscription. For a full discussion of the subscription resource, see Subscription. Subscriptions can be filtered for one or more customers by using the customer_id or external_customer_id query parameters. Subscriptions can be filtered by one or more statuses (each one of active, ended, or upcoming) using the status query parameter, e.g. status[]=active&status[]=ended. description here description here description here here description here here here description here

Parameters:

  • limit (Integer) (defaults to: 20) —

    Optional parameter: Example:20

  • cursor (String) (defaults to: nil) —

    Optional parameter: TODO: type description here

  • customer_id (Array[String]) (defaults to: nil) —

    Optional parameter: TODO: type

  • external_customer_id (Array[String]) (defaults to: nil) —

    Optional parameter: TODO: type

  • plan_id (String) (defaults to: nil) —

    Optional parameter: TODO: type description here

  • external_plan_id (String) (defaults to: nil) —

    Optional parameter: TODO: type

  • status (Array[Status28]) (defaults to: nil) —

    Optional parameter: TODO: type description

  • created_at_gte (DateTime) (defaults to: nil) —

    Optional parameter: TODO: type

  • created_at_gt (DateTime) (defaults to: nil) —

    Optional parameter: TODO: type description

  • created_at_lt (DateTime) (defaults to: nil) —

    Optional parameter: TODO: type description

  • created_at_lte (DateTime) (defaults to: nil) —

    Optional parameter: TODO: type

Returns:

  • (ApiResponse) —

    Complete http response with raw body and status code.



39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
 
# File 'lib/api_reference/apis/subscription_api.rb', line 39

def list_subscriptions(limit: 20,
                       cursor: nil,
                       customer_id: nil,
                       external_customer_id: nil,
                       plan_id: nil,
                       external_plan_id: nil,
                       status: nil,
                       created_at_gte: nil,
                       created_at_gt: nil,
                       created_at_lt: nil,
                       created_at_lte: nil)
  @api_call
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/subscriptions',
                                 Server::DEFAULT)
               .query_param(new_parameter(limit, key: 'limit'))
               .query_param(new_parameter(cursor, key: 'cursor'))
               .query_param(new_parameter(customer_id, key: 'customer_id[]'))
               .query_param(new_parameter(external_customer_id, key: 'external_customer_id[]'))
               .query_param(new_parameter(plan_id, key: 'plan_id'))
               .query_param(new_parameter(external_plan_id, key: 'external_plan_id'))
               .query_param(new_parameter(status, key: 'status[]'))
               .query_param(new_parameter(created_at_gte, key: 'created_at[gte]'))
               .query_param(new_parameter(created_at_gt, key: 'created_at[gt]'))
               .query_param(new_parameter(created_at_lt, key: 'created_at[lt]'))
               .query_param(new_parameter(created_at_lte, key: 'created_at[lte]'))
               .header_param(new_parameter('application/json', key: 'accept'))
               .auth(Single.new('APIKeyAuth')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(Subscriptions.method(:from_hash))
                .is_api_response(true)
                .local_error('400',
                             'Bad Request',
                             APIException)
                .local_error('401',
                             'Unauthorized',
                             AuthorizationErrorException)
                .local_error('404',
                             'Not Found',
                             APIException)
                .local_error('409',
                             'Conflict',
                             IdempotencyRequestMismatchException)
                .local_error('413',
                             'Content Too Large',
                             APIException)
                .local_error('429',
                             'Too Many Requests',
                             TooManyRequestsException)
                .local_error('500',
                             'Internal Server Error',
                             ServerErrorException))
    .execute
end

#redeem_coupon(subscription_id, body) ⇒ ApiResponse

Redeem a coupon effective at a given time. here description here

Parameters:

  • subscription_id (String) —

    Required parameter: TODO: type description

  • body (RedeemCouponParams) —

    Required parameter: TODO: type

Returns:

  • (ApiResponse) —

    Complete http response with raw body and status code.



656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
 
# File 'lib/api_reference/apis/subscription_api.rb', line 656

def redeem_coupon(subscription_id,
                  body)
  @api_call
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/subscriptions/{subscription_id}/redeem_coupon',
                                 Server::DEFAULT)
               .template_param(new_parameter(subscription_id, key: 'subscription_id')
                                .is_required(true)
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .body_param(new_parameter(body)
                            .is_required(true))
               .header_param(new_parameter('application/json', key: 'accept'))
               .body_serializer(proc do |param| param.to_json unless param.nil? end)
               .auth(Single.new('APIKeyAuth')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(MutatedSubscription.method(:from_hash))
                .is_api_response(true)
                .local_error('400',
                             'Bad Request',
                             APIException)
                .local_error('401',
                             'Unauthorized',
                             AuthorizationErrorException)
                .local_error('404',
                             'Not Found',
                             APIException)
                .local_error('409',
                             'Conflict',
                             IdempotencyRequestMismatchException)
                .local_error('413',
                             'Content Too Large',
                             APIException)
                .local_error('429',
                             'Too Many Requests',
                             TooManyRequestsException)
                .local_error('500',
                             'Internal Server Error',
                             ServerErrorException))
    .execute
end

#schedule_plan_change(subscription_id, body) ⇒ ApiResponse

This endpoint can be used to change an existing subscription's plan. It returns the serialized updated subscription object. The body parameter change_option determines when the plan change occurs. Orb supports three options:

  • end_of_subscription_term: changes the plan at the end of the existing plan's term.
    • Issuing this plan change request for a monthly subscription will keep the existing plan active until the start of the subsequent month. Issuing this plan change request for a yearly subscription will keep the existing plan active for the full year. Charges incurred in the remaining period will be invoiced as normal.
    • Example: The plan is billed monthly on the 1st of the month, the request is made on January 15th, so the plan will be changed on February 1st, and invoice will be issued on February 1st for the last month of the original plan.
  • immediate: changes the plan immediately.
    • Subscriptions that have their plan changed with this option will move to the new plan immediately, and be invoiced immediately.
    • This invoice will include any usage fees incurred in the billing period up to the change, along with any prorated recurring fees for the billing period, if applicable.
    • Example: The plan is billed monthly on the 1st of the month, the request is made on January 15th, so the plan will be changed on January 15th, and an invoice will be issued for the partial month, from January 1 to January 15, on the original plan.
  • requested_date: changes the plan on the requested date (change_date).
    • If no timezone is provided, the customer's timezone is used. The change_date body parameter is required if this option is chosen.
    • Example: The plan is billed monthly on the 1st of the month, the request is made on January 15th, with a requested change_date of February 15th, so the plan will be changed on February 15th, and invoices will be issued on February 1st and February 15th. Note that one of plan_id or external_plan_id is required in the request body for this operation.

Customize your customer's subscriptions

Prices and adjustments in a plan can be added, removed, or replaced on the subscription when you schedule the plan change. This is useful when a customer has prices that differ from the default prices for a specific plan. This feature is only available for accounts that have migrated to Subscription Overrides Version 2. You can find your Subscription Overrides Version at the bottom of your Plans page

Adding Prices

To add prices, provide a list of objects with the key add_prices. An object in the list must specify an existing add-on price with a price_id or external_price_id field, or create a new add-on price by including an object with the key price, identical to what would be used in the request body for the create price endpoint. See the Price resource for the specification of different price model configurations possible in this object. If the plan has phases, each object in the list must include a number with plan_phase_order key to indicate which phase the price should be added to. An object in the list can specify an optional start_date and optional end_date. If start_date is unspecified, the start of the phase / plan change time will be used. If end_date is unspecified, it will finish at the end of the phase / have no end time. An object in the list can specify an optional minimum_amount, maximum_amount, or discounts. This will create adjustments which apply only to this price. Additionally, an object in the list can specify an optional reference_id. This ID can be used to reference this price when adding an adjustment in the same API call. However the ID is transient and cannot be used to refer to the price in future API calls.

Removing Prices

To remove prices, provide a list of objects with the key remove_prices. An object in the list must specify a plan price with either a price_id or external_price_id field.

Replacing Prices

To replace prices, provide a list of objects with the key replace_prices. An object in the list must specify a plan price to replace with the replaces_price_id key, and it must specify a price to replace it with by either referencing an existing add-on price with a price_id or external_price_id field, or by creating a new add-on price by including an object with the key price, identical to what would be used in the request body for the create price endpoint. See the Price resource for the specification of different price model configurations possible in this object. For fixed fees, an object in the list can supply a fixed_price_quantity instead of a price, price_id, or external_price_id field. This will update only the quantity for the price, similar to the Update price quantity endpoint. The replacement price will have the same phase, if applicable, and the same start and end dates as the price it replaces. An object in the list can specify an optional minimum_amount, maximum_amount, or discounts. This will create adjustments which apply only to this price. Additionally, an object in the list can specify an optional reference_id. This ID can be used to reference the replacement price when adding an adjustment in the same API call. However the ID is transient and cannot be used to refer to the price in future API calls.

Adding adjustments

To add adjustments, provide a list of objects with the key add_adjustments. An object in the list must include an object with the key adjustment, identical to the adjustment object in the add/edit price intervals endpoint. If the plan has phases, each object in the list must include a number with plan_phase_order key to indicate which phase the adjustment should be added to. An object in the list can specify an optional start_date and optional end_date. If start_date is unspecified, the start of the phase / plan change time will be used. If end_date is unspecified, it will finish at the end of the phase / have no end time.

Removing adjustments

To remove adjustments, provide a list of objects with the key remove_adjustments. An object in the list must include a key, adjustment_id, with the ID of the adjustment to be removed.

Replacing adjustments

To replace adjustments, provide a list of objects with the key replace_adjustments. An object in the list must specify a plan adjustment to replace with the replaces_adjustment_id key, and it must specify an adjustment to replace it with by including an object with the key adjustment, identical to the adjustment object in the add/edit price intervals endpoint. The replacement adjustment will have the same phase, if applicable, and the same start and end dates as the adjustment it replaces.

Price overrides (DEPRECATED)

Price overrides are being phased out in favor adding/removing/replacing prices. (See [Customize your customer's subscriptions](/api-reference/subscription/schedule-plan-change)) Price overrides are used to update some or all prices in a plan for the specific subscription being created. This is useful when a new customer has negotiated a rate that is unique to the customer. To override prices, provide a list of objects with the key `price_overrides`. The price object in the list of overrides is expected to contain the existing price id, the `model_type` and configuration. (See the [Price resource](/product-catalog/price-configuration) for the specification of different price model configurations.) The numerical values can be updated, but the billable metric, cadence, type, and name of a price can not be overridden. ### Maximums, and minimums Price overrides are used to update some or all prices in the target plan. Minimums and maximums, much like price overrides, can be useful when a new customer has negotiated a new or different minimum or maximum spend cap than the default for the plan. The request format for maximums and minimums is the same as those in [subscription creation](create-subscription). ## Scheduling multiple plan changes When scheduling multiple plan changes with the same date, the latest plan change on that day takes effect. ## Prorations for in-advance fees By default, Orb calculates the prorated difference in any fixed fees when making a plan change, adjusting the customer balance as needed. For details on this behavior, see [Modifying subscriptions](/product-catalog/modifying-subscriptions#prorations-for-in- advance-fees). here description here

Parameters:

  • subscription_id (String) —

    Required parameter: TODO: type description

  • body (SubscriptionPlanChange) —

    Required parameter: TODO: type

Returns:

  • (ApiResponse) —

    Complete http response with raw body and status code.



948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
 
# File 'lib/api_reference/apis/subscription_api.rb', line 948

def schedule_plan_change(subscription_id,
                         body)
  @api_call
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/subscriptions/{subscription_id}/schedule_plan_change',
                                 Server::DEFAULT)
               .template_param(new_parameter(subscription_id, key: 'subscription_id')
                                .is_required(true)
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .body_param(new_parameter(body)
                            .is_required(true))
               .header_param(new_parameter('application/json', key: 'accept'))
               .body_serializer(proc do |param| param.to_json unless param.nil? end)
               .auth(Single.new('APIKeyAuth')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(MutatedSubscription.method(:from_hash))
                .is_api_response(true)
                .local_error('400',
                             'Bad Request',
                             APIException)
                .local_error('401',
                             'Unauthorized',
                             AuthorizationErrorException)
                .local_error('404',
                             'Not Found',
                             APIException)
                .local_error('409',
                             'Conflict',
                             IdempotencyRequestMismatchException)
                .local_error('413',
                             'Content Too Large',
                             APIException)
                .local_error('429',
                             'Too Many Requests',
                             TooManyRequestsException)
                .local_error('500',
                             'Internal Server Error',
                             ServerErrorException))
    .execute
end

#trigger_phase(subscription_id, body) ⇒ ApiResponse

Manually trigger a phase, effective the given date (or the current time, if not specified). here type description here

Parameters:

Returns:

  • (ApiResponse) —

    Complete http response with raw body and status code.



998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
 
# File 'lib/api_reference/apis/subscription_api.rb', line 998

def trigger_phase(subscription_id,
                  body)
  @api_call
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/subscriptions/{subscription_id}/trigger_phase',
                                 Server::DEFAULT)
               .template_param(new_parameter(subscription_id, key: 'subscription_id')
                                .is_required(true)
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .body_param(new_parameter(body)
                            .is_required(true))
               .header_param(new_parameter('application/json', key: 'accept'))
               .body_serializer(proc do |param| param.to_json unless param.nil? end)
               .auth(Single.new('APIKeyAuth')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(MutatedSubscription.method(:from_hash))
                .is_api_response(true)
                .local_error('400',
                             'Bad Request',
                             APIException)
                .local_error('401',
                             'Unauthorized',
                             AuthorizationErrorException)
                .local_error('404',
                             'Not Found',
                             APIException)
                .local_error('409',
                             'Conflict',
                             IdempotencyRequestMismatchException)
                .local_error('413',
                             'Content Too Large',
                             APIException)
                .local_error('429',
                             'Too Many Requests',
                             TooManyRequestsException)
                .local_error('500',
                             'Internal Server Error',
                             ServerErrorException))
    .execute
end

#unschedule_cancellation(subscription_id) ⇒ ApiResponse

This endpoint can be used to unschedule any pending cancellations for a subscription. To be eligible, the subscription must currently be active and have a future cancellation. This operation will turn on auto-renew, ensuring that the subscription does not end at the currently scheduled cancellation time. Note: uncancellation is a lossy operation. Price intervals that were cut short by the cancellation are extended to infinity (original end dates are lost), and future intervals or phases scheduled after the cancellation time are permanently deleted. For complex subscriptions with phases or scheduled plan changes, consider creating a new plan change instead of uncancelling. here

Parameters:

  • subscription_id (String) —

    Required parameter: TODO: type description

Returns:

  • (ApiResponse) —

    Complete http response with raw body and status code.



1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
 
# File 'lib/api_reference/apis/subscription_api.rb', line 1057

def unschedule_cancellation(subscription_id)
  @api_call
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/subscriptions/{subscription_id}/unschedule_cancellation',
                                 Server::DEFAULT)
               .template_param(new_parameter(subscription_id, key: 'subscription_id')
                                .is_required(true)
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'accept'))
               .auth(Single.new('APIKeyAuth')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(MutatedSubscription.method(:from_hash))
                .is_api_response(true)
                .local_error('400',
                             'Bad Request',
                             APIException)
                .local_error('401',
                             'Unauthorized',
                             AuthorizationErrorException)
                .local_error('404',
                             'Not Found',
                             APIException)
                .local_error('409',
                             'Conflict',
                             IdempotencyRequestMismatchException)
                .local_error('413',
                             'Content Too Large',
                             APIException)
                .local_error('429',
                             'Too Many Requests',
                             TooManyRequestsException)
                .local_error('500',
                             'Internal Server Error',
                             ServerErrorException))
    .execute
end

#unschedule_fixed_fee_quantity(subscription_id, body) ⇒ ApiResponse

This endpoint can be used to clear scheduled updates to the quantity for a fixed fee. If there are no updates scheduled, a request validation error will be returned with a 400 status code. here TODO: type description here

Parameters:

Returns:

  • (ApiResponse) —

    Complete http response with raw body and status code.



1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
 
# File 'lib/api_reference/apis/subscription_api.rb', line 1104

def unschedule_fixed_fee_quantity(subscription_id,
                                  body)
  @api_call
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/subscriptions/{subscription_id}/unschedule_fixed_fee_quantity_updates',
                                 Server::DEFAULT)
               .template_param(new_parameter(subscription_id, key: 'subscription_id')
                                .is_required(true)
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .body_param(new_parameter(body)
                            .is_required(true))
               .header_param(new_parameter('application/json', key: 'accept'))
               .body_serializer(proc do |param| param.to_json unless param.nil? end)
               .auth(Single.new('APIKeyAuth')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(MutatedSubscription.method(:from_hash))
                .is_api_response(true)
                .local_error('400',
                             'Bad Request',
                             APIException)
                .local_error('401',
                             'Unauthorized',
                             AuthorizationErrorException)
                .local_error('404',
                             'Not Found',
                             APIException)
                .local_error('409',
                             'Conflict',
                             IdempotencyRequestMismatchException)
                .local_error('413',
                             'Content Too Large',
                             APIException)
                .local_error('429',
                             'Too Many Requests',
                             TooManyRequestsException)
                .local_error('500',
                             'Internal Server Error',
                             ServerErrorException))
    .execute
end

#unschedule_plan_change(subscription_id) ⇒ ApiResponse

This endpoint can be used to unschedule any pending plan changes on an existing subscription. When called, all upcoming plan changes will be unscheduled. here

Parameters:

  • subscription_id (String) —

    Required parameter: TODO: type description

Returns:

  • (ApiResponse) —

    Complete http response with raw body and status code.



1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
 
# File 'lib/api_reference/apis/subscription_api.rb', line 1153

def unschedule_plan_change(subscription_id)
  @api_call
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/subscriptions/{subscription_id}/unschedule_pending_plan_changes',
                                 Server::DEFAULT)
               .template_param(new_parameter(subscription_id, key: 'subscription_id')
                                .is_required(true)
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'accept'))
               .auth(Single.new('APIKeyAuth')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(MutatedSubscription.method(:from_hash))
                .is_api_response(true)
                .local_error('400',
                             'Bad Request',
                             APIException)
                .local_error('401',
                             'Unauthorized',
                             AuthorizationErrorException)
                .local_error('404',
                             'Not Found',
                             APIException)
                .local_error('409',
                             'Conflict',
                             IdempotencyRequestMismatchException)
                .local_error('413',
                             'Content Too Large',
                             APIException)
                .local_error('429',
                             'Too Many Requests',
                             TooManyRequestsException)
                .local_error('500',
                             'Internal Server Error',
                             ServerErrorException))
    .execute
end

#update_fixed_fee_quantity(subscription_id, body) ⇒ ApiResponse

This endpoint can be used to update the quantity for a fixed fee. To be eligible, the subscription must currently be active and the price specified must be a fixed fee (not usage-based). This operation will immediately update the quantity for the fee, or if a effective_date is passed in, will update the quantity on the requested date at midnight in the customer's timezone. In order to change the fixed fee quantity as of the next draft invoice for this subscription, pass change_option=upcoming_invoice without an effective_date specified. If the fee is an in-advance fixed fee, it will also issue an immediate invoice for the difference for the remainder of the billing period. here description here

Parameters:

  • subscription_id (String) —

    Required parameter: TODO: type description

  • body (FixedFeeQuantityChange) —

    Required parameter: TODO: type

Returns:

  • (ApiResponse) —

    Complete http response with raw body and status code.



1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
 
# File 'lib/api_reference/apis/subscription_api.rb', line 1209

def update_fixed_fee_quantity(subscription_id,
                              body)
  @api_call
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/subscriptions/{subscription_id}/update_fixed_fee_quantity',
                                 Server::DEFAULT)
               .template_param(new_parameter(subscription_id, key: 'subscription_id')
                                .is_required(true)
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .body_param(new_parameter(body)
                            .is_required(true))
               .header_param(new_parameter('application/json', key: 'accept'))
               .body_serializer(proc do |param| param.to_json unless param.nil? end)
               .auth(Single.new('APIKeyAuth')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(MutatedSubscription.method(:from_hash))
                .is_api_response(true)
                .local_error('400',
                             'Bad Request',
                             APIException)
                .local_error('401',
                             'Unauthorized',
                             AuthorizationErrorException)
                .local_error('404',
                             'Not Found',
                             APIException)
                .local_error('409',
                             'Conflict',
                             IdempotencyRequestMismatchException)
                .local_error('413',
                             'Content Too Large',
                             APIException)
                .local_error('429',
                             'Too Many Requests',
                             TooManyRequestsException)
                .local_error('500',
                             'Internal Server Error',
                             ServerErrorException))
    .execute
end

#update_subscription(subscription_id, body) ⇒ ApiResponse

This endpoint can be used to update the metadata, net terms, auto_collection, invoicing_threshold, and default_invoice_memo properties on a subscription. here description here

Parameters:

  • subscription_id (String) —

    Required parameter: TODO: type description

  • body (UpdateSubscriptionParams) —

    Required parameter: TODO: type

Returns:

  • (ApiResponse) —

    Complete http response with raw body and status code.



424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
 
# File 'lib/api_reference/apis/subscription_api.rb', line 424

def update_subscription(subscription_id,
                        body)
  @api_call
    .request(new_request_builder(HttpMethodEnum::PUT,
                                 '/subscriptions/{subscription_id}',
                                 Server::DEFAULT)
               .template_param(new_parameter(subscription_id, key: 'subscription_id')
                                .is_required(true)
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .body_param(new_parameter(body)
                            .is_required(true))
               .header_param(new_parameter('application/json', key: 'accept'))
               .body_serializer(proc do |param| param.to_json unless param.nil? end)
               .auth(Single.new('APIKeyAuth')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(Subscription.method(:from_hash))
                .is_api_response(true)
                .local_error('400',
                             'Bad Request',
                             APIException)
                .local_error('401',
                             'Unauthorized',
                             AuthorizationErrorException)
                .local_error('404',
                             'Not Found',
                             APIException)
                .local_error('409',
                             'Conflict',
                             IdempotencyRequestMismatchException)
                .local_error('413',
                             'Content Too Large',
                             APIException)
                .local_error('429',
                             'Too Many Requests',
                             TooManyRequestsException)
                .local_error('500',
                             'Internal Server Error',
                             ServerErrorException))
    .execute
end

#update_trial(subscription_id, body) ⇒ ApiResponse

This endpoint is used to update the trial end date for a subscription. The new trial end date must be within the time range of the current plan (i.e. the new trial end date must be on or after the subscription's start date on the current plan, and on or before the subscription end date). In order to retroactively remove a trial completely, the end date can be set to the transition date of the subscription to this plan (or, if this is the first plan for this subscription, the subscription's start date). In order to end a trial immediately, the keyword immediate can be provided as the trial end date. By default, Orb will shift only the trial end date (and price intervals that start or end on the previous trial end date), and leave all other future price intervals untouched. If the shift parameter is set to true, Orb will shift all subsequent price and adjustment intervals by the same amount as the trial end date shift (so, e.g., if a plan change is scheduled or an add-on price was added, that change will be pushed back by the same amount of time the trial is extended). here description here

Parameters:

  • subscription_id (String) —

    Required parameter: TODO: type description

  • body (UpdateTrialRequestParams) —

    Required parameter: TODO: type

Returns:

  • (ApiResponse) —

    Complete http response with raw body and status code.



1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
 
# File 'lib/api_reference/apis/subscription_api.rb', line 1275

def update_trial(subscription_id,
                 body)
  @api_call
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/subscriptions/{subscription_id}/update_trial',
                                 Server::DEFAULT)
               .template_param(new_parameter(subscription_id, key: 'subscription_id')
                                .is_required(true)
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .body_param(new_parameter(body)
                            .is_required(true))
               .header_param(new_parameter('application/json', key: 'accept'))
               .body_serializer(proc do |param| param.to_json unless param.nil? end)
               .auth(Single.new('APIKeyAuth')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(MutatedSubscription.method(:from_hash))
                .is_api_response(true)
                .local_error('400',
                             'Bad Request',
                             APIException)
                .local_error('401',
                             'Unauthorized',
                             AuthorizationErrorException)
                .local_error('404',
                             'Not Found',
                             APIException)
                .local_error('409',
                             'Conflict',
                             IdempotencyRequestMismatchException)
                .local_error('413',
                             'Content Too Large',
                             APIException)
                .local_error('429',
                             'Too Many Requests',
                             TooManyRequestsException)
                .local_error('500',
                             'Internal Server Error',
                             ServerErrorException))
    .execute
end