Welcome
Guides
Wingback.js
Advanced
curl --request POST \
--url http://127.0.0.1:8080/v1/c/contract/{contract_id}/upgrade_estimate \
--header 'Content-Type: application/json' \
--header 'wb-key: <api-key>' \
--data '
{
"upgrade_configuration": {
"activation": {
"type": "next_cycle"
},
"currency": "usd",
"cycle": "once",
"plan_id": "Cust_c40bea18-c0c9-44b1-bd0c-43f5283e1670",
"unit_configuration": {},
"unit_count_configuration": {},
"upgrade_strategy": "new_plan",
"discount_id": "Cust_c40bea18-c0c9-44b1-bd0c-43f5283e1670",
"pricing_id": "Cust_c40bea18-c0c9-44b1-bd0c-43f5283e1670"
},
"downgrade_allowed": true
}
'{
"is_downgrade": true,
"price_on_new_contract": [
{
"invoice": {
"currency": "usd",
"customer_id": "Cust_c40bea18-c0c9-44b1-bd0c-43f5283e1670",
"date": "2023-11-07T05:31:56Z",
"deposit_transaction_status": "not_processed",
"due_date": "2023-11-07T05:31:56Z",
"id": "Cust_c40bea18-c0c9-44b1-bd0c-43f5283e1670",
"invoice_number": {
"number": "<string>"
},
"status": "pending_validation",
"total": "<string>",
"deposit_transaction_id": "Cust_c40bea18-c0c9-44b1-bd0c-43f5283e1670",
"external_reference": "<string>"
},
"invoice_items": [
{
"charge_id": "Cust_c40bea18-c0c9-44b1-bd0c-43f5283e1670",
"currency": "usd",
"due_date": "2023-11-07T05:31:56Z",
"id": "Cust_c40bea18-c0c9-44b1-bd0c-43f5283e1670",
"name": "<string>",
"scheduling_policy": "immediate",
"status": "pending_validation",
"subtotal": "<string>",
"total_excluding_tax": "<string>",
"total_including_tax": "<string>",
"unit_count": "<string>",
"unit_price": "<string>",
"description": "<string>",
"discount_amount": "<string>",
"discount_description": "<string>",
"invoice_id": "Cust_c40bea18-c0c9-44b1-bd0c-43f5283e1670",
"tax_amount": "<string>",
"tax_code": "<string>",
"tax_policy": "tax_included",
"withdrawal_transaction_id": "Cust_c40bea18-c0c9-44b1-bd0c-43f5283e1670"
}
]
}
],
"pro_rate_new_contract": "<string>",
"pro_rate_old_contract": "<string>",
"remains_to_pay_current_contract": [
{
"invoice": {
"currency": "usd",
"customer_id": "Cust_c40bea18-c0c9-44b1-bd0c-43f5283e1670",
"date": "2023-11-07T05:31:56Z",
"deposit_transaction_status": "not_processed",
"due_date": "2023-11-07T05:31:56Z",
"id": "Cust_c40bea18-c0c9-44b1-bd0c-43f5283e1670",
"invoice_number": {
"number": "<string>"
},
"status": "pending_validation",
"total": "<string>",
"deposit_transaction_id": "Cust_c40bea18-c0c9-44b1-bd0c-43f5283e1670",
"external_reference": "<string>"
},
"invoice_items": [
{
"charge_id": "Cust_c40bea18-c0c9-44b1-bd0c-43f5283e1670",
"currency": "usd",
"due_date": "2023-11-07T05:31:56Z",
"id": "Cust_c40bea18-c0c9-44b1-bd0c-43f5283e1670",
"name": "<string>",
"scheduling_policy": "immediate",
"status": "pending_validation",
"subtotal": "<string>",
"total_excluding_tax": "<string>",
"total_including_tax": "<string>",
"unit_count": "<string>",
"unit_price": "<string>",
"description": "<string>",
"discount_amount": "<string>",
"discount_description": "<string>",
"invoice_id": "Cust_c40bea18-c0c9-44b1-bd0c-43f5283e1670",
"tax_amount": "<string>",
"tax_code": "<string>",
"tax_policy": "tax_included",
"withdrawal_transaction_id": "Cust_c40bea18-c0c9-44b1-bd0c-43f5283e1670"
}
]
}
],
"upgrade_cost_breakdown": {
"new_contract": {
"cost_pro_rated": "<string>",
"cycle": "once",
"full_cost": "<string>",
"pro_rate": "<string>",
"time_on_contract": {
"period": {
"end": "2023-11-07T05:31:56Z",
"start": "2023-11-07T05:31:56Z"
},
"time_used": {
"unit": "hour",
"unit_count": 123
}
},
"usage": "<string>"
},
"new_contract_cost_pro_rated": "<string>",
"old_contract": {
"cost_pro_rated": "<string>",
"cycle": "once",
"full_cost": "<string>",
"pro_rate": "<string>",
"time_on_contract": {
"period": {
"end": "2023-11-07T05:31:56Z",
"start": "2023-11-07T05:31:56Z"
},
"time_used": {
"unit": "hour",
"unit_count": 123
}
},
"usage": "<string>"
},
"pro_rate_new_contract": "<string>",
"pro_rate_old_contract": "<string>",
"total": "<string>",
"usage_old_contract": "<string>",
"time_on_new_contract": {
"unit": "hour",
"value": 123
},
"time_on_old_contract": {
"unit": "hour",
"value": 123
}
},
"usage_old_contract": "<string>",
"new_contract_period": {
"end": "2023-11-07T05:31:56Z",
"start": "2023-11-07T05:31:56Z"
}
}Estimate Upgrade Costss
Estimate plan upgrade costs.
curl --request POST \
--url http://127.0.0.1:8080/v1/c/contract/{contract_id}/upgrade_estimate \
--header 'Content-Type: application/json' \
--header 'wb-key: <api-key>' \
--data '
{
"upgrade_configuration": {
"activation": {
"type": "next_cycle"
},
"currency": "usd",
"cycle": "once",
"plan_id": "Cust_c40bea18-c0c9-44b1-bd0c-43f5283e1670",
"unit_configuration": {},
"unit_count_configuration": {},
"upgrade_strategy": "new_plan",
"discount_id": "Cust_c40bea18-c0c9-44b1-bd0c-43f5283e1670",
"pricing_id": "Cust_c40bea18-c0c9-44b1-bd0c-43f5283e1670"
},
"downgrade_allowed": true
}
'{
"is_downgrade": true,
"price_on_new_contract": [
{
"invoice": {
"currency": "usd",
"customer_id": "Cust_c40bea18-c0c9-44b1-bd0c-43f5283e1670",
"date": "2023-11-07T05:31:56Z",
"deposit_transaction_status": "not_processed",
"due_date": "2023-11-07T05:31:56Z",
"id": "Cust_c40bea18-c0c9-44b1-bd0c-43f5283e1670",
"invoice_number": {
"number": "<string>"
},
"status": "pending_validation",
"total": "<string>",
"deposit_transaction_id": "Cust_c40bea18-c0c9-44b1-bd0c-43f5283e1670",
"external_reference": "<string>"
},
"invoice_items": [
{
"charge_id": "Cust_c40bea18-c0c9-44b1-bd0c-43f5283e1670",
"currency": "usd",
"due_date": "2023-11-07T05:31:56Z",
"id": "Cust_c40bea18-c0c9-44b1-bd0c-43f5283e1670",
"name": "<string>",
"scheduling_policy": "immediate",
"status": "pending_validation",
"subtotal": "<string>",
"total_excluding_tax": "<string>",
"total_including_tax": "<string>",
"unit_count": "<string>",
"unit_price": "<string>",
"description": "<string>",
"discount_amount": "<string>",
"discount_description": "<string>",
"invoice_id": "Cust_c40bea18-c0c9-44b1-bd0c-43f5283e1670",
"tax_amount": "<string>",
"tax_code": "<string>",
"tax_policy": "tax_included",
"withdrawal_transaction_id": "Cust_c40bea18-c0c9-44b1-bd0c-43f5283e1670"
}
]
}
],
"pro_rate_new_contract": "<string>",
"pro_rate_old_contract": "<string>",
"remains_to_pay_current_contract": [
{
"invoice": {
"currency": "usd",
"customer_id": "Cust_c40bea18-c0c9-44b1-bd0c-43f5283e1670",
"date": "2023-11-07T05:31:56Z",
"deposit_transaction_status": "not_processed",
"due_date": "2023-11-07T05:31:56Z",
"id": "Cust_c40bea18-c0c9-44b1-bd0c-43f5283e1670",
"invoice_number": {
"number": "<string>"
},
"status": "pending_validation",
"total": "<string>",
"deposit_transaction_id": "Cust_c40bea18-c0c9-44b1-bd0c-43f5283e1670",
"external_reference": "<string>"
},
"invoice_items": [
{
"charge_id": "Cust_c40bea18-c0c9-44b1-bd0c-43f5283e1670",
"currency": "usd",
"due_date": "2023-11-07T05:31:56Z",
"id": "Cust_c40bea18-c0c9-44b1-bd0c-43f5283e1670",
"name": "<string>",
"scheduling_policy": "immediate",
"status": "pending_validation",
"subtotal": "<string>",
"total_excluding_tax": "<string>",
"total_including_tax": "<string>",
"unit_count": "<string>",
"unit_price": "<string>",
"description": "<string>",
"discount_amount": "<string>",
"discount_description": "<string>",
"invoice_id": "Cust_c40bea18-c0c9-44b1-bd0c-43f5283e1670",
"tax_amount": "<string>",
"tax_code": "<string>",
"tax_policy": "tax_included",
"withdrawal_transaction_id": "Cust_c40bea18-c0c9-44b1-bd0c-43f5283e1670"
}
]
}
],
"upgrade_cost_breakdown": {
"new_contract": {
"cost_pro_rated": "<string>",
"cycle": "once",
"full_cost": "<string>",
"pro_rate": "<string>",
"time_on_contract": {
"period": {
"end": "2023-11-07T05:31:56Z",
"start": "2023-11-07T05:31:56Z"
},
"time_used": {
"unit": "hour",
"unit_count": 123
}
},
"usage": "<string>"
},
"new_contract_cost_pro_rated": "<string>",
"old_contract": {
"cost_pro_rated": "<string>",
"cycle": "once",
"full_cost": "<string>",
"pro_rate": "<string>",
"time_on_contract": {
"period": {
"end": "2023-11-07T05:31:56Z",
"start": "2023-11-07T05:31:56Z"
},
"time_used": {
"unit": "hour",
"unit_count": 123
}
},
"usage": "<string>"
},
"pro_rate_new_contract": "<string>",
"pro_rate_old_contract": "<string>",
"total": "<string>",
"usage_old_contract": "<string>",
"time_on_new_contract": {
"unit": "hour",
"value": 123
},
"time_on_old_contract": {
"unit": "hour",
"value": 123
}
},
"usage_old_contract": "<string>",
"new_contract_period": {
"end": "2023-11-07T05:31:56Z",
"start": "2023-11-07T05:31:56Z"
}
}Authorizations
Path Parameters
Id of the Contract
Body
Upgrade configuration used when WbCustomer is performing a Contract Upgrade for a Customer
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.
- Option 1
- Option 2
- Option 3
Show child attributes
Show child attributes
Configuration to choose the date when upgrade takes place:
- NextCycle - at the beginning of the next billing cycle
- Date - at the specific date (UTC)
- Option 1
- Option 2
Show child attributes
Show child attributes
next_cycle A supported currency
The format for parsing and reading is the lowercased ISO 4217 currency code (e.g. "usd")
usd, eur, gbp, brl, ars 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
once, hour, day, week, month, quarter, year, constant Unique identifier of an object. Consists of object class prefix and a UUID
"Cust_c40bea18-c0c9-44b1-bd0c-43f5283e1670"
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
Show child attributes
Show child attributes
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
Show child attributes
Show child attributes
the overridden flat_fee for the usage-based feature
the overridden price of the given feature
used for optional features - the optional feature is added to the contract only if this
is set to true
Override tiers
Show child attributes
Show child attributes
Price per unit for this tier
Number of units where this tier starts applying.
the number of units being purchased
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} }
Show child attributes
Show child attributes
new_plan Unique identifier of an object. Consists of object class prefix and a UUID
"Cust_c40bea18-c0c9-44b1-bd0c-43f5283e1670"
Unique identifier of an object. Consists of object class prefix and a UUID
"Cust_c40bea18-c0c9-44b1-bd0c-43f5283e1670"
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
Response
Upgraded
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 16end-of-month will be pro-rated - for the new contract, days 1~15 will be unused and pro-rated
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
Estimated invoices of the first billing period for the new Contract
Show child attributes
Show child attributes
Overall information about the issued invoice
Show child attributes
Show child attributes
A supported currency
The format for parsing and reading is the lowercased ISO 4217 currency code (e.g. "usd")
usd, eur, gbp, brl, ars Unique identifier of an object. Consists of object class prefix and a UUID
"Cust_c40bea18-c0c9-44b1-bd0c-43f5283e1670"
Date when the invoice was created
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)
not_processed, customer_not_active, canceled_unpaid_transaction, canceled_self_handled_payment, no_valid_payment_method, sum_smaller_than_payment_threshold, created Date the invoice is due
Unique identifier of an object. Consists of object class prefix and a UUID
"Cust_c40bea18-c0c9-44b1-bd0c-43f5283e1670"
Status of the invoice:
- PendingValidation - Invoice awaits manual review
- ReadyForPayment - invoice can be paid
- Paid - invoice was paid
pending_validation, ready_for_payment, paid Total sum of the invoice
Unique identifier of an object. Consists of object class prefix and a UUID
"Cust_c40bea18-c0c9-44b1-bd0c-43f5283e1670"
Optional reference in a non-wingback system
InvoiceItems of the Invoice
Show child attributes
Show child attributes
Unique identifier of an object. Consists of object class prefix and a UUID
"Cust_c40bea18-c0c9-44b1-bd0c-43f5283e1670"
A supported currency
The format for parsing and reading is the lowercased ISO 4217 currency code (e.g. "usd")
usd, eur, gbp, brl, ars Due date of this invoice item
Unique identifier of an object. Consists of object class prefix and a UUID
"Cust_c40bea18-c0c9-44b1-bd0c-43f5283e1670"
Name of the feature this InvoiceItem is for
Scheduling policy for invoice items:
- Immediate - Invoicing (and payments if automated) must be immediate
- Periodic - Scheduling is normal for the contract, allowing batches
immediate, periodic Status of the invoice item:
- PendingValidation - invoice item awaits manual review
- Validated - invoice item is ready to be attached to an invoice
pending_validation, validated Subtotal. Unit price * unit count
Subtotal minus the discount
Total excluding tax with added tax
Number of units. For flat price features this will be 1
Price of each unit of this feature
Description of this InvoiceItem
Amount discounted
Description of the discount used for this invoice item
Unique identifier of an object. Consists of object class prefix and a UUID
"Cust_c40bea18-c0c9-44b1-bd0c-43f5283e1670"
Amount of tax
Tax code
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
tax_included, tax_on_top Unique identifier of an object. Consists of object class prefix and a UUID
"Cust_c40bea18-c0c9-44b1-bd0c-43f5283e1670"
Pro rated amount on the new contract. Deprecated, please use UpgradeCostBreakdown.
Pro rated amount for the current contract. Deprecated, please use UpgradeCostBreakdown.
Invoices for the current Contract
Show child attributes
Show child attributes
Overall information about the issued invoice
Show child attributes
Show child attributes
A supported currency
The format for parsing and reading is the lowercased ISO 4217 currency code (e.g. "usd")
usd, eur, gbp, brl, ars Unique identifier of an object. Consists of object class prefix and a UUID
"Cust_c40bea18-c0c9-44b1-bd0c-43f5283e1670"
Date when the invoice was created
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)
not_processed, customer_not_active, canceled_unpaid_transaction, canceled_self_handled_payment, no_valid_payment_method, sum_smaller_than_payment_threshold, created Date the invoice is due
Unique identifier of an object. Consists of object class prefix and a UUID
"Cust_c40bea18-c0c9-44b1-bd0c-43f5283e1670"
An invoice number, unique per wb_customer
The current format is
<wb_customer-customer-key>-<year>-<customer-sequential-number>
Show child attributes
Show child attributes
The invoice number, unique
Status of the invoice:
- PendingValidation - Invoice awaits manual review
- ReadyForPayment - invoice can be paid
- Paid - invoice was paid
pending_validation, ready_for_payment, paid Total sum of the invoice
Unique identifier of an object. Consists of object class prefix and a UUID
"Cust_c40bea18-c0c9-44b1-bd0c-43f5283e1670"
Optional reference in a non-wingback system
InvoiceItems of the Invoice
Show child attributes
Show child attributes
Unique identifier of an object. Consists of object class prefix and a UUID
"Cust_c40bea18-c0c9-44b1-bd0c-43f5283e1670"
A supported currency
The format for parsing and reading is the lowercased ISO 4217 currency code (e.g. "usd")
usd, eur, gbp, brl, ars Due date of this invoice item
Unique identifier of an object. Consists of object class prefix and a UUID
"Cust_c40bea18-c0c9-44b1-bd0c-43f5283e1670"
Name of the feature this InvoiceItem is for
Scheduling policy for invoice items:
- Immediate - Invoicing (and payments if automated) must be immediate
- Periodic - Scheduling is normal for the contract, allowing batches
immediate, periodic Status of the invoice item:
- PendingValidation - invoice item awaits manual review
- Validated - invoice item is ready to be attached to an invoice
pending_validation, validated Subtotal. Unit price * unit count
Subtotal minus the discount
Total excluding tax with added tax
Number of units. For flat price features this will be 1
Price of each unit of this feature
Description of this InvoiceItem
Amount discounted
Description of the discount used for this invoice item
Unique identifier of an object. Consists of object class prefix and a UUID
"Cust_c40bea18-c0c9-44b1-bd0c-43f5283e1670"
Amount of tax
Tax code
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
tax_included, tax_on_top Unique identifier of an object. Consists of object class prefix and a UUID
"Cust_c40bea18-c0c9-44b1-bd0c-43f5283e1670"
Additional information about upgrade costs
Show child attributes
Show child attributes
Describes the calculation of pro-rated cost for contract upgrade
Show child attributes
Show child attributes
The amount that IS charged (cost - pro rate)
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
once, hour, day, week, month, quarter, year, constant Cost if the contract were used for the whole period
Pro rated amount
Additional description of how much time was spent on the contract in the billing period of the upgrade
Show child attributes
Show child attributes
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
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
cost of all usage-based features
price of the new contract without discount from old contract applied
Describes the calculation of pro-rated cost for contract upgrade
Show child attributes
Show child attributes
The amount that IS charged (cost - pro rate)
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
once, hour, day, week, month, quarter, year, constant Cost if the contract were used for the whole period
Pro rated amount
Additional description of how much time was spent on the contract in the billing period of the upgrade
Show child attributes
Show child attributes
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
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
cost of all usage-based features
Pro rated amount for the new contract. Deprecated, please use ContractProRateBreakdown.
Pro rated amount for the current contract. Deprecated, please use ContractProRateBreakdown.
Total upgrade cost
If old contract has usage-priced features, this indicates how much will be paid for usage on upgrade. Deprecated, please use ContractProRateBreakdown.
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
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
If old contract has usage-priced features, this indicates how much will be paid for usage on upgrade. Deprecated, please use UpgradeCostBreakdown.
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