Class: ApiReference::PriceIntervalApi

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

Overview

PriceIntervalApi

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

#add_edit_price_intervals(subscription_id, body) ⇒ ApiResponse

This endpoint is used to add and edit subscription price intervals. By making modifications to a subscription’s price intervals, you can flexibly and atomically control the billing behavior of a subscription.

Adding price intervals

Prices can be added as price intervals to a subscription by specifying them in the add array. A price_id or external_price_id from an add-on price or previously removed plan price can be specified to reuse an existing price definition (however, please note that prices from other plans cannot be added to the subscription). Additionally, a new price can be specified using the price field — this price will be created automatically. A start_date must be specified for the price interval. This is the date when the price will start billing on the subscription, so this will notably result in an immediate charge at this time for any billed in advance fixed fees. The end_date will default to null, resulting in a price interval that will bill on a continually recurring basis. Both of these dates can be set in the past or the future and Orb will generate or modify invoices to ensure the subscription’s invoicing behavior is correct. Additionally, a discount, minimum, or maximum can be specified on the price interval. This will only apply to this price interval, not any other price intervals on the subscription.

Adjustment intervals

An adjustment interval represents the time period that a particular adjustment (a discount, minimum, or maximum) applies to the prices on a subscription. Adjustment intervals can be added to a subscription by specifying them in the add_adjustments array, or modified via the edit_adjustments array. When creating an adjustment interval, you'll need to provide the definition of the new adjustment (the type of adjustment, and which prices it applies to), as well as the start and end dates for the adjustment interval. The start and end dates of an existing adjustment interval can be edited via the edit_adjustments field (just like price intervals). (To "change" the amount of a discount, minimum, or maximum, then, you'll need to end the existing interval, and create a new adjustment interval with the new amount and a start date that matches the end date of the previous interval.)

Editing price intervals

Price intervals can be adjusted by specifying edits to make in the edit array. A price_interval_id to edit must be specified — this can be retrieved from the price_intervals field on the subscription. A new start_date or end_date can be specified to change the range of the price interval, which will modify past or future invoices to ensure correctness. If either of these dates are unspecified, they will default to the existing date on the price interval. To remove a price interval entirely from a subscription, set the end_date to be equivalent to the start_date.

Fixed fee quantity transitions

The fixed fee quantity transitions for a fixed fee price interval can also be specified when adding or editing by passing an array for fixed_fee_quantity_transitions. A fixed fee quantity transition must have a quantity and an effective_date, which is the date after which the new quantity will be used for billing. If a fixed fee quantity transition is scheduled at a billing period boundary, the full quantity will be billed on an invoice with the other prices on the subscription. If the fixed fee quantity transition is scheduled mid-billing period, the difference between the existing quantity and quantity specified in the transition will be prorated for the rest of the billing period and billed immediately, which will generate a new invoice. Notably, the list of fixed fee quantity transitions passed will overwrite the existing fixed fee quantity transitions on the price interval, so the entire list of transitions must be specified to add additional transitions. The existing list of transitions can be retrieved using the fixed_fee_quantity_transitions property on a subscription’s serialized price intervals. here description here

Parameters:

  • subscription_id (String) —

    Required parameter: TODO: type description

  • body (AddEditPriceIntervalParams) —

    Required parameter: TODO: type

Returns:

  • (ApiResponse) —

    Complete http response with raw body and status code.



91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
 
# File 'lib/api_reference/apis/price_interval_api.rb', line 91

def add_edit_price_intervals(subscription_id,
                             body)
  @api_call
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/subscriptions/{subscription_id}/price_intervals',
                                 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