> ## Documentation Index
> Fetch the complete documentation index at: https://docs-int.wingback.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Estimate Upgrade Costss
> Estimate plan upgrade costs.
export const IntRedir = () => {
if (typeof document === "undefined") {
return null;
} else {
setTimeout(() => {
const currentUrl = new URL(window.location.href);
if (currentUrl.hostname === 'docs-int.wingback.com') {
currentUrl.hostname = 'docs.wingback.com';
window.location.replace(currentUrl.toString());
}
}, 1);
return <>;
}
};
## OpenAPI
````yaml POST /v1/c/contract/{contract_id}/upgrade_estimate
openapi: 3.0.3
info:
title: wingback-api
description: ''
contact:
name: ''
license:
name: commercial
version: 0.1.0
servers:
- url: http://127.0.0.1:8080
description: Local server
- url: https://api.app.test.wingback.com
description: Testing server
security: []
paths:
/v1/c/contract/{contract_id}/upgrade_estimate:
post:
tags:
- contract
operationId: upgrade_contract_estimate
parameters:
- name: contract_id
in: path
description: Id of the Contract
required: true
schema:
type: string
example: Cont_cc871a3a-2b38-4689-a32d-14bf2e62b1ae
requestBody:
content:
application/json:
schema:
$ref: >-
#/components/schemas/inbound.contract.WbCustomerUpgradeConfiguration
required: true
responses:
'200':
description: Upgraded
content:
application/json:
schema:
$ref: '#/components/schemas/outbound.contract.ContractUpgradeEstimate'
security:
- api-key: []
- wb_user_cookie: []
components:
schemas:
inbound.contract.WbCustomerUpgradeConfiguration:
type: object
description: >-
Upgrade configuration used when WbCustomer is performing a Contract
Upgrade for a Customer
required:
- upgrade_configuration
properties:
downgrade_allowed:
type: boolean
description: >-
By default downgrading to a cheaper plan can only be done at the end
of the billing cycle
This is done to avoid the need to refund unused part of the current
billing cycle
from the old contract
However, WbCustomer may override this behaviour, and force immediate
downgrade by
setting this argument to `true`.
Default is `false`
upgrade_configuration:
$ref: '#/components/schemas/UpgradeConfiguration'
outbound.contract.ContractUpgradeEstimate:
type: object
description: >-
Estimate of the price of the Contract Upgrade
When contract upgrade is performed mid-cycle, but the billing period is
kept the same,
the unused part of the current contract billing period, as well as the
unused part
of the new contract's billing period will be accordingly pro-rated
For example, if the contract is paid on the 1st of every month
and the upgrade is performed on 16th, we pro-rate as follows:
- days 1~15 of the old contract are considered "used", remainder is
"unused"
thus, days 16~end-of-month will be pro-rated
- for the new contract, days 1~15 will be unused and pro-rated
required:
- remains_to_pay_current_contract
- price_on_new_contract
- pro_rate_old_contract
- pro_rate_new_contract
- usage_old_contract
- upgrade_cost_breakdown
- is_downgrade
properties:
is_downgrade:
type: boolean
description: >-
If contract change is downgrade (a move to a cheaper contract), then
this will be set to
True. Downgrade can not be performed mid-cycle, only at the end of
the billing cycle
new_contract_period:
allOf:
- $ref: '#/components/schemas/Period'
nullable: true
price_on_new_contract:
type: array
items:
$ref: '#/components/schemas/outbound.invoice.InvoiceSummary'
description: Estimated invoices of the first billing period for the new Contract
pro_rate_new_contract:
type: string
description: >-
Pro rated amount on the new contract. Deprecated, please use
UpgradeCostBreakdown.
pro_rate_old_contract:
type: string
description: >-
Pro rated amount for the current contract. Deprecated, please use
UpgradeCostBreakdown.
remains_to_pay_current_contract:
type: array
items:
$ref: '#/components/schemas/outbound.invoice.InvoiceSummary'
description: Invoices for the current Contract
upgrade_cost_breakdown:
$ref: '#/components/schemas/outbound.contract.UpgradeCostBreakdown'
usage_old_contract:
type: string
description: >-
If old contract has usage-priced features, this indicates how much
will be paid for usage on upgrade. Deprecated, please use
UpgradeCostBreakdown.
UpgradeConfiguration:
oneOf:
- allOf:
- $ref: '#/components/schemas/PlanUpgrade'
- type: object
required:
- upgrade_strategy
properties:
upgrade_strategy:
type: string
enum:
- new_plan
- allOf:
- $ref: '#/components/schemas/UnitCountUpgrade'
- type: object
required:
- upgrade_strategy
properties:
upgrade_strategy:
type: string
enum:
- change_unit_count
- allOf:
- $ref: '#/components/schemas/BillingDateConfiguration'
- type: object
required:
- upgrade_strategy
properties:
upgrade_strategy:
type: string
enum:
- change_billing_date
description: >-
Type of plan upgrade:
* NewPlan - upgrade to a different plan
* ChangeUnitCount - only increase or decrease the number of purchased
units for the current plan
The main difference between ChangeUnitCount and using NewPlan with the
ID of the same plan
is that if the prices of features changed between contract creation and
current time,
ChangeUnitCount will preserve the prices of features recorded in the
contract,
while using NewPlan will also mean that new prices will take effect.
discriminator:
propertyName: upgrade_strategy
Period:
type: object
description: >-
Billing period of the contract. For example, for contracts that are paid
monthly,
a new billing period would be created each month. For Constant or Once
contracts, a single
period would be created with empty "end" value
required:
- start
- end
properties:
end:
type: string
format: date-time
description: End of the billing period
start:
type: string
format: date-time
description: Start of the billing period
outbound.invoice.InvoiceSummary:
type: object
description: Helper type that reports both Invoice and its InvoiceItems
required:
- invoice
- invoice_items
properties:
invoice:
$ref: '#/components/schemas/Invoice'
invoice_items:
type: array
items:
$ref: '#/components/schemas/InvoiceItem'
description: InvoiceItems of the Invoice
outbound.contract.UpgradeCostBreakdown:
type: object
description: Additional information about upgrade costs
required:
- pro_rate_old_contract
- pro_rate_new_contract
- usage_old_contract
- total
- new_contract_cost_pro_rated
- old_contract
- new_contract
properties:
new_contract:
$ref: '#/components/schemas/ContractProRateBreakdown'
new_contract_cost_pro_rated:
type: string
description: price of the new contract without discount from old contract applied
old_contract:
$ref: '#/components/schemas/ContractProRateBreakdown'
pro_rate_new_contract:
type: string
description: >-
Pro rated amount for the new contract. Deprecated, please use
ContractProRateBreakdown.
pro_rate_old_contract:
type: string
description: >-
Pro rated amount for the current contract. Deprecated, please use
ContractProRateBreakdown.
time_on_new_contract:
allOf:
- $ref: '#/components/schemas/outbound.contract.BillingTimeUnit'
nullable: true
time_on_old_contract:
allOf:
- $ref: '#/components/schemas/outbound.contract.BillingTimeUnit'
nullable: true
total:
type: string
description: Total upgrade cost
usage_old_contract:
type: string
description: >-
If old contract has usage-priced features, this indicates how much
will be paid for usage on upgrade. Deprecated, please use
ContractProRateBreakdown.
PlanUpgrade:
type: object
description: Configuration for upgrading from one plan to another
required:
- plan_id
- cycle
- currency
- activation
- unit_count_configuration
- unit_configuration
properties:
activation:
$ref: '#/components/schemas/UpgradeActivation'
currency:
$ref: '#/components/schemas/Currency'
cycle:
$ref: '#/components/schemas/Cycle'
discount_id:
allOf:
- $ref: '#/components/schemas/Id'
nullable: true
plan_id:
$ref: '#/components/schemas/Id'
pricing_id:
allOf:
- $ref: '#/components/schemas/Id'
nullable: true
unit_configuration:
type: object
description: >-
Configuration specifying overrides to apply to new plan during
contract upgrade.
In addition to the number of units to purchase, it is possible to
override price and flat_fee of specific features to create
customized plans
See UnitConfiguration for format
additionalProperties:
$ref: '#/components/schemas/FeatureConfigurationInternal'
unit_count_configuration:
type: object
description: >-
Configuration specifying the number of units to purchase
on the new plan for unit-based features. This is a hashmap where
keys are slugs of features, and values are the numbers of units to
purchase
{
"{feature_slug}": {number_of_units}
}
additionalProperties:
type: string
UnitCountUpgrade:
type: object
description: >-
Configuration to only change the amount of purchased units in the active
contract
required:
- activation
- unit_count_configuration
properties:
activation:
$ref: '#/components/schemas/UpgradeActivation'
discount_id:
allOf:
- $ref: '#/components/schemas/Id'
nullable: true
unit_count_configuration:
type: object
description: >-
Configuration specifying the number of units to purchase
on the new plan for unit-based features. This is a hashmap where
keys are slugs of features, and values are the numbers of units to
purchase
{
"{feature_slug}": {number_of_units}
}
additionalProperties:
type: string
BillingDateConfiguration:
type: object
description: Configuration to only change the billing date of the active contract
required:
- date
- recalculate_charges
properties:
date:
type: string
format: date-time
description: >-
New billing date. All subsequent charges will occur on the same day
of the billing cycle.
discount_id:
allOf:
- $ref: '#/components/schemas/Id'
nullable: true
recalculate_charges:
type: boolean
description: >-
Determines if the customer will be charged for the difference in
days/months
between old and new billing dates
Invoice:
type: object
description: Overall information about the issued invoice
required:
- id
- customer_id
- date
- status
- total
- currency
- deposit_transaction_status
- due_date
- invoice_number
properties:
currency:
$ref: '#/components/schemas/Currency'
customer_id:
$ref: '#/components/schemas/Id'
date:
type: string
format: date-time
description: Date when the invoice was created
deposit_transaction_id:
allOf:
- $ref: '#/components/schemas/Id'
nullable: true
deposit_transaction_status:
$ref: '#/components/schemas/InvoiceDepositStatus'
due_date:
type: string
format: date-time
description: Date the invoice is due
external_reference:
type: string
description: Optional reference in a non-wingback system
nullable: true
id:
$ref: '#/components/schemas/Id'
invoice_number:
$ref: '#/components/schemas/InvoiceNumber'
status:
$ref: '#/components/schemas/InvoiceStatus'
total:
type: string
description: Total sum of the invoice
InvoiceItem:
type: object
description: >-
Invoice Item, or in other words Invoice Line.
An invoice always consists of one or more Invoice Item, which is a
concrete
charge for a concrete feature. The invoice item contains full
information about:
* the feature that is being billed for
* the amount of units of the feature that is being charged for
* discounts and taxes applied
required:
- id
- status
- scheduling_policy
- charge_id
- name
- unit_price
- unit_count
- subtotal
- total_excluding_tax
- total_including_tax
- currency
- due_date
properties:
charge_id:
$ref: '#/components/schemas/Id'
currency:
$ref: '#/components/schemas/Currency'
description:
type: string
description: Description of this InvoiceItem
nullable: true
discount_amount:
type: string
description: Amount discounted
nullable: true
discount_description:
type: string
description: Description of the discount used for this invoice item
nullable: true
due_date:
type: string
format: date-time
description: Due date of this invoice item
id:
$ref: '#/components/schemas/Id'
invoice_id:
allOf:
- $ref: '#/components/schemas/Id'
nullable: true
name:
type: string
description: Name of the feature this InvoiceItem is for
scheduling_policy:
$ref: '#/components/schemas/InvoiceSchedulingPolicy'
status:
$ref: '#/components/schemas/InvoiceItemStatus'
subtotal:
type: string
description: Subtotal. Unit price * unit count
tax_amount:
type: string
description: Amount of tax
nullable: true
tax_code:
type: string
description: Tax code
nullable: true
tax_policy:
allOf:
- $ref: '#/components/schemas/TaxPolicy'
nullable: true
total_excluding_tax:
type: string
description: Subtotal minus the discount
total_including_tax:
type: string
description: Total excluding tax with added tax
unit_count:
type: string
description: Number of units. For flat price features this will be 1
unit_price:
type: string
description: Price of each unit of this feature
withdrawal_transaction_id:
allOf:
- $ref: '#/components/schemas/Id'
nullable: true
ContractProRateBreakdown:
type: object
description: Describes the calculation of pro-rated cost for contract upgrade
required:
- full_cost
- cycle
- cost_pro_rated
- pro_rate
- usage
- time_on_contract
properties:
cost_pro_rated:
type: string
description: The amount that IS charged (cost - pro rate)
cycle:
$ref: '#/components/schemas/Cycle'
full_cost:
type: string
description: Cost if the contract were used for the whole period
pro_rate:
type: string
description: Pro rated amount
time_on_contract:
$ref: '#/components/schemas/TimeOnContract'
usage:
type: string
description: cost of all usage-based features
outbound.contract.BillingTimeUnit:
type: object
description: >-
This is used to report how many days or month we consider as used on old
contract,
and how many will be used on the new contract during contract upgrade
Because depending on the billing cycle duration, the resolution to which
we compute this
changes, we supply value and units separately. For example, for monthly
contracts
we will report number of days used, and for yearly - number of months
required:
- value
- unit
properties:
unit:
$ref: '#/components/schemas/TimeUnit'
value:
type: integer
format: int32
description: Amount of time units
UpgradeActivation:
oneOf:
- type: object
required:
- type
properties:
type:
type: string
enum:
- next_cycle
- type: object
required:
- upgrade_date
- type
properties:
type:
type: string
enum:
- date
upgrade_date:
type: string
format: date-time
description: Date of the upgrade
description: |-
Configuration to choose the date when upgrade takes place:
* NextCycle - at the beginning of the next billing cycle
* Date - at the specific date (UTC)
discriminator:
propertyName: type
Currency:
type: string
description: |-
A supported currency
The format for parsing and reading is the lowercased
ISO 4217 currency code (e.g. "usd")
enum:
- usd
- eur
- gbp
- brl
- ars
Cycle:
type: string
description: |-
Enum that lists supported payment cycles for contracts:
* Once - one-time payment
* Constant - one-time payment for the duration of the contract
* Week - contract is paid weekly
* Month - contract is paid monthly
* Quarter - contract is paid every quarter
* Year - contract is paid yearly
enum:
- once
- hour
- day
- week
- month
- quarter
- year
- constant
Id:
type: string
description: >-
Unique identifier of an object. Consists of object class prefix and a
UUID
example: Cust_c40bea18-c0c9-44b1-bd0c-43f5283e1670
FeatureConfigurationInternal:
type: object
description: >-
Helper structure to store the overridden price and flat_fee for
customized
contracts, as well as the number of units being purchased for the
contract
properties:
flat_fee:
type: string
description: the overridden flat_fee for the usage-based feature
nullable: true
price:
type: string
description: the overridden price of the given feature
nullable: true
purchased:
type: boolean
description: >-
used for optional features - the optional feature is added to the
contract only if this
is set to `true`
nullable: true
tiers:
type: array
items:
$ref: '#/components/schemas/Tier'
description: Override tiers
nullable: true
unit_count:
type: string
description: the number of units being purchased
nullable: true
InvoiceDepositStatus:
type: string
description: |-
Status of the deposit transaction creation, which
explains, whent the deposit transaction wasn't
created, why it's the case.
This status isn't meant for (wb_)customer display
as it's quite technical. For this purpose,
see DetailedInvoiceStatus.
When the invoice holds a deposit transaction id,
then this status is *always* Created (enforced by
DB constraint)
enum:
- not_processed
- customer_not_active
- canceled_unpaid_transaction
- canceled_self_handled_payment
- no_valid_payment_method
- sum_smaller_than_payment_threshold
- created
InvoiceNumber:
type: object
description: |-
An invoice number, unique per wb_customer
The current format is
`--`
required:
- number
properties:
number:
type: string
description: The invoice number, unique
InvoiceStatus:
type: string
description: |-
Status of the invoice:
* PendingValidation - Invoice awaits manual review
* ReadyForPayment - invoice can be paid
* Paid - invoice was paid
enum:
- pending_validation
- ready_for_payment
- paid
InvoiceSchedulingPolicy:
type: string
description: |-
Scheduling policy for invoice items:
* Immediate - Invoicing (and payments if automated) must be immediate
* Periodic - Scheduling is normal for the contract, allowing batches
enum:
- immediate
- periodic
InvoiceItemStatus:
type: string
description: |-
Status of the invoice item:
* PendingValidation - invoice item awaits manual review
* Validated - invoice item is ready to be attached to an invoice
enum:
- pending_validation
- validated
TaxPolicy:
type: string
description: >-
Two options for handling taxes:
- TaxIncluded means that unit_price already includes tax, and so true
unit_price
equals to: unit_price = true unit_price + tax. True unit_price will be
adjusted
on the invoice so that the final price matches desired price in the
unit_price
field
- TaxOnTop means that unit_price is true unit_price, tax will be added
on top, and
unit_price will not be changed as a result of the tax calculation
enum:
- tax_included
- tax_on_top
TimeOnContract:
type: object
description: >-
Additional description of how much time was spent on the contract in the
billing period
of the upgrade
properties:
period:
allOf:
- $ref: '#/components/schemas/Period'
nullable: true
time_used:
allOf:
- $ref: '#/components/schemas/ContractTimeUsage'
nullable: true
TimeUnit:
type: string
description: Type of time unit
enum:
- hour
- day
- month
Tier:
type: object
description: A pricing tier
required:
- tier_start
- tier_end
- amount
properties:
amount:
type: string
description: Price per unit for this tier
tier_end:
$ref: '#/components/schemas/TierValue'
tier_start:
type: string
description: Number of units where this tier starts applying.
ContractTimeUsage:
type: object
description: >-
How much time was counted as being on the contract in the given period
Since billing periods of different duration are supported, we describe
the time in terms
of time units. For example, for monthly contracts, the unit of time
would be a day,
but for contracts paid yearly, the unit of time is month
required:
- unit_count
- unit
properties:
unit:
$ref: '#/components/schemas/TimeUnit'
unit_count:
type: integer
format: int32
description: The number of time units
TierValue:
oneOf:
- type: object
required:
- Concrete
properties:
Concrete:
type: string
- type: string
enum:
- Infinity
description: Either a number of `infinity`. Must be a string
securitySchemes:
api-key:
type: apiKey
in: header
name: wb-key
wb_user_cookie:
type: apiKey
in: cookie
name: app-session
````