Documentation
Documentation
https://docs.togai.com/api-reference/getting-started
GettingStarted
https://docs.togai.com/docs/introduction
OpenAPI Specification
openapi: 3.0.3
info:
version: '1.0'
title: Togai Apis Accounts Price Experimentation API
contact:
email: engg@togai.com
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
description: APIs for Togai App
servers:
- description: Api endpoint
url: https://api.togai.com/
- description: Sandbox api endpoint
url: https://sandbox-api.togai.com/
security:
- bearerAuth: []
tags:
- name: Price Experimentation
description: Price Experimentation apis
paths:
/revenue_calculator:
post:
tags:
- Price Experimentation
summary: Calculate and Return the Revenue for a Existing or New Price Plan
description: Calculate and return the revenue for a existing or new price plan
operationId: calculateRevenue
requestBody:
$ref: '#/components/requestBodies/CalculateRevenueRequest'
responses:
'200':
$ref: '#/components/responses/CalculateRevenueResponse'
'400':
$ref: '#/components/responses/ErrorResponse'
'401':
$ref: '#/components/responses/ErrorResponse'
'403':
$ref: '#/components/responses/ErrorResponse'
'404':
$ref: '#/components/responses/ErrorResponse'
'429':
$ref: '#/components/responses/ErrorResponse'
default:
$ref: '#/components/responses/ErrorResponse'
components:
schemas:
MaxQuantityBreachAction:
type: string
enum:
- DO_NOTHING
description: "Action to be taken when the license maxQuantity is breached: \n- `DO_NOTHING`: Refrain from granting any new licenses.\n"
ProratedRefundMode:
type: string
enum:
- NONE
- CREDITS
- PAYMENT
- WALLET
UsageCycleInterval:
type: string
description: "UsageCycleInterval field allows you to treat the billing interval as many smaller windows. Revenue is calculated for\neach of the windows (usage cycles) and their sum is considered as the billing interval revenue.\nExample: 1 Named License being used across entire billing interval. Rate Value: $1/license\nCASE 1: Without usage cycle. $1 is charged for the entire billing cycle.\nCASE 2: Usage cycle is configure to be WEEKLY and the billing interval has 4 weeks. In this case $1 is charged \nfor each week totalling to $4 across for the billing interval\n"
enum:
- WEEKLY
- MONTHLY
- QUARTERLY
- HALF_YEARLY
- ANNUALLY
LicenseRateCardConfig:
title: LicenseRateCardConfig
type: object
properties:
maxQuantity:
description: Max allowed quantity for a particular license in a price plan
type: integer
format: int64
example: 100
maxQuantityBreachAction:
$ref: '#/components/schemas/MaxQuantityBreachAction'
AddOnType:
type: string
enum:
- LICENSE
- FIXED_FEE
- CREDIT_GRANT
- NAMED_LICENSE
description: 'LICENSE: Addon can be used in license rate cards
FIXED_FEE: Addon can be used in fixed fee rate cards
CREDIT_GRANT: Addon can be used in credit grant rate cards
NAMED_LICENSE: Addon can be used in license rate cards
'
FixedFeeRateCard:
title: FixedFeeRateCard
type: object
required:
- id
- rateValues
- enableProration
properties:
id:
description: Unique Identifier of the attached AddOn
type: string
maxLength: 50
displayName:
type: string
description: Name of the attached AddOn
tag:
type: string
description: A tag string to group fixedFeeRateCards
invoiceTiming:
$ref: '#/components/schemas/InvoiceTiming'
type:
$ref: '#/components/schemas/FixedFeeType'
rateValues:
type: array
items:
$ref: '#/components/schemas/CurrencyRateValue'
enableProration:
type: boolean
example: false
recurrenceConfig:
$ref: '#/components/schemas/RecurrenceConfig'
CreditGrantRateCard:
description: Credit grant rate card
type: object
additionalProperties: false
required:
- id
- rateDetails
- grantDetails
properties:
id:
type: string
displayName:
type: string
tag:
type: string
description: A tag string to group creditGrantRateCard
grantDetails:
$ref: '#/components/schemas/GrantDetails'
rateDetails:
$ref: '#/components/schemas/CreditRateDetails'
invoiceTiming:
$ref: '#/components/schemas/InvoiceTiming'
type:
$ref: '#/components/schemas/CreditGrantType'
recurrenceConfig:
$ref: '#/components/schemas/RecurrenceConfig'
CreditGrantType:
type: string
enum:
- ONE_TIME
- RECURRING
description: Credit grant applies either for a one-time occurrence or for each cycle.
ErrorResponse:
type: object
additionalProperties: false
required:
- message
properties:
message:
type: string
description: error description
maxLength: 500
PricePlanType:
type: string
description: Type of price plan
enum:
- BILLING
- PURCHASE
SlabRevenueSummary:
type: object
additionalProperties: false
required:
- order
- usage
- revenue
properties:
order:
type: integer
usage:
type: number
revenue:
type: number
metadata:
title: SlabRevenueMetadata
type: object
additionalProperties: false
properties:
minimumRateApplied:
type: boolean
maximumRateApplied:
type: boolean
packageQuantity:
type: integer
RecurrenceConfig:
type: object
properties:
interval:
description: Represents the number of pricing cycles after which the rate card will be charged
type: integer
format: int64
example: 3
offset:
description: Represents the offset for pricing cycles after which the rate card will be charged
type: integer
format: int64
example: 5
FixedFeeType:
type: string
enum:
- ONE_TIME
- RECURRING
description: Fixed fee applies either for a one-time occurrence or for each cycle.
ExpiryType:
type: string
description: Expiry type of grant
enum:
- PRICING_CYCLE
- NO_EXPIRY
- CUSTOM
UsageRateCard:
type: object
required:
- usageMeterId
- ratePlan
- rateValues
properties:
displayName:
type: string
description: Name your rate card, this will be displayed in the Togai App
tag:
type: string
description: A tag string to group usageRateCards
usageMeterId:
type: string
example: um.1zYnCiM9Bpg.1zYn
ratePlan:
$ref: '#/components/schemas/RatePlan'
rateValues:
type: array
items:
$ref: '#/components/schemas/RateValue'
CalculateRevenueResponse:
type: object
additionalProperties: false
required:
- revenueInfo
- pricePlanDetails
- currency
properties:
currency:
type: string
usageLookupRange:
type: object
title: UsageLookupRange
description: Start and end dates of usage lookup if usage mode is LOOKUP
additionalProperties: false
required:
- start
- end
properties:
start:
type: string
format: date-time
end:
type: string
format: date-time
pricePlanDetails:
$ref: '#/components/schemas/PricePlanDetails'
revenueInfo:
type: array
items:
title: RevenueInfo
type: object
additionalProperties: false
required:
- usages
properties:
usageRateCard:
$ref: '#/components/schemas/UsageRateCard'
fixedFeeRateCard:
$ref: '#/components/schemas/FixedFeeRateCard'
licenseRateCard:
$ref: '#/components/schemas/LicenseRateCard'
billingEntitlementRateCard:
$ref: '#/components/schemas/BillingEntitlementRateCard'
creditGrantRateCard:
$ref: '#/components/schemas/CreditGrantRateCard'
entitlementOverageRateCard:
$ref: '#/components/schemas/EntitlementOverageRateCard'
usages:
type: object
additionalProperties:
type: number
fixedFeeRevenueSummary:
type: object
title: FixedFeeRevenueSummary
additionalProperties: false
required:
- revenue
properties:
revenue:
type: number
licenseRevenueSummary:
type: array
items:
$ref: '#/components/schemas/SlabRevenueSummary'
billingEntitlementRevenueSummary:
type: object
title: BillingEntitlementRevenueSummary
additionalProperties: false
required:
- revenue
properties:
revenue:
type: number
creditGrantRevenueSummary:
type: object
title: CreditGrantRevenueSummary
additionalProperties: false
required:
- revenue
properties:
revenue:
type: number
entitlementOverageRevenueSummary:
type: object
title: EntitlementOverageRevenueSummary
additionalProperties: false
required:
- revenue
properties:
revenue:
type: number
slabRevenueSummaries:
type: array
items:
$ref: '#/components/schemas/SlabRevenueSummary'
CalculateRevenueRequest:
description: Request to get revenue details
type: object
additionalProperties: false
required:
- currencyConfig
- pricePlanDetailsConfig
- usageConfig
- licenseEntriesConfig
properties:
currencyConfig:
title: CurrencyConfig
description: Configuration for getting the currency
type: object
required:
- mode
properties:
mode:
type: string
enum:
- CUSTOM
- ACCOUNT_INVOICE
description: 'Mode to get the currency
- CUSTOM: Use the currency provided in the request
- ACCOUNT_INVOICE: Use the invoice currency of the given account
'
currency:
description: Currency to be used, this will be considered if mode is CUSTOM
type: string
minLength: 1
accountId:
description: Id of the account of which invoice currency will be used, this will be considered if mode is ACCOUNT_INVOICE
type: string
pricePlanDetailsConfig:
title: PricePlanDetailsConfig
description: Configuration for getting the usage rate card
type: object
required:
- mode
properties:
mode:
type: string
enum:
- CUSTOM
- PRICE_PLAN
- ACCOUNT
description: 'Mode to get the usage rate card
- CUSTOM: Use the price plan details provided in the request
- PRICE_PLAN: Use the usage rate cards of the given price plan
- ACCOUNT: Use the usage rate cards of a associated price plan of the given account
'
pricePlanDetails:
$ref: '#/components/schemas/CreatePricePlanDetails'
pricePlanId:
description: Id of the price plan, this will be considered if mode is PRICE_PLAN
type: string
minLength: 1
accountId:
description: Id of the account, this will be considered if mode is ACCOUNT
type: string
minLength: 1
effectiveOn:
description: Will be used for getting the usage rate card, only used if mode is ACCOUNT or PRICE_PLAN
type: string
format: date-time
pricingCycleOrdinal:
description: nth cycle, will be used to calculate revenue for the particular cycle, only used if mode is CUSTOM or PRICE_PLAN
type: integer
usageConfig:
title: UsageConfig
description: Configuration for getting the usage
type: object
required:
- mode
properties:
mode:
type: string
enum:
- CUSTOM
- LOOKUP_RANGE
- LOOKUP_CYCLE
description: 'Mode to get the usage for the usage meters
- CUSTOM: Use the usages provided in the request
- LOOKUP_RANGE: Use the usage of a given account for the specified range
- LOOKUP_CYCLE: Use the usage of a given account for the specified cycle
'
usageMap:
description: Map of usage meter id and usage, this will be considered if mode is CUSTOM
type: object
additionalProperties:
type: number
lookupRange:
description: Range of usage to be looked up, this will be considered if mode is LOOKUP_RANGE
type: object
required:
- start
- end
- accountId
properties:
start:
type: string
format: date-time
end:
type: string
format: date-time
accountId:
type: string
minLength: 1
lookupCycle:
description: Cycle of usage to be looked up, this will be considered if mode is LOOKUP_CYCLE
type: object
required:
- accountId
properties:
cycleEffectiveOn:
type: string
format: date-time
accountId:
type: string
minLength: 1
licenseEntriesConfig:
title: LicenseEntriesConfig
description: Configuration for getting the license entries
type: object
required:
- mode
properties:
mode:
type: string
enum:
- CUSTOM
- LOOKUP_RANGE
- LOOKUP_CYCLE
description: 'Mode to get the license entries for the license rate cards
- CUSTOM: Use the license entries provided in the request
- LOOKUP_RANGE: Use the license entries of a given account for the specified range
- LOOKUP_CYCLE: Use the license entries of a given account for the specified cycle
'
custom:
description: List of license entries, this will be considered if mode is CUSTOM
type: array
items:
type: object
title: LicenseEntry
required:
- licenseId
- quantity
- effectiveFrom
properties:
licenseId:
type: string
minLength: 1
quantity:
type: integer
effectiveFrom:
type: string
format: date-time
lookupRange:
description: Range of license entries to be looked up, this will be considered if mode is LOOKUP_RANGE
type: object
required:
- start
- end
- accountId
properties:
start:
type: string
format: date-time
end:
type: string
format: date-time
accountId:
type: string
minLength: 1
lookupCycle:
description: Cycle of license entries to be looked up, this will be considered if mode is LOOKUP_CYCLE
type: object
required:
- accountId
properties:
cycleEffectiveOn:
description: Effective date of the cycle, will be used to get the license entries of the cycle
type: string
format: date-time
accountId:
type: string
minLength: 1
namedLicenseEntriesConfig:
title: NamedLicenseEntriesConfig
description: Configuration for getting the named license entries
type: object
required:
- mode
properties:
mode:
type: string
enum:
- CUSTOM
- LOOKUP_RANGE
- LOOKUP_CYCLE
description: 'Mode to get the named license entries for the license rate cards
- CUSTOM: Use the named license entries provided in the request
- LOOKUP_RANGE: Use the named license entries of a given account for the specified range
- LOOKUP_CYCLE: Use the named license entries of a given account for the specified cycle
'
custom:
description: List of named license entries, this will be considered if mode is CUSTOM
type: array
items:
type: object
title: NamedLicenseEntry
required:
- licenseId
- name
- effectiveFrom
properties:
licenseId:
type: string
minLength: 1
name:
type: integer
effectiveFrom:
type: string
format: date-time
effectiveUntil:
type: string
format: date-time
lookupRange:
description: Range of named license entries to be looked up, this will be considered if mode is LOOKUP_RANGE
type: object
required:
- start
- end
- accountId
properties:
start:
type: string
format: date-time
end:
type: string
format: date-time
accountId:
type: string
minLength: 1
lookupCycle:
description: Cycle of named license entries to be looked up, this will be considered if mode is LOOKUP_CYCLE
type: object
required:
- accountId
properties:
cycleEffectiveOn:
description: Effective date of the cycle, will be used to get the named license entries of the cycle
type: string
format: date-time
accountId:
type: string
minLength: 1
prorationConfig:
title: ProrationConfig
description: Configuration for getting the proration, if not provided no proration will be applied
type: object
required:
- mode
properties:
mode:
type: string
enum:
- CUSTOM
- LOOKUP_CYCLE
description: 'Mode to get the proration
- CUSTOM: Use the proration provided in the request
- LOOKUP_CYCLE: Use the proration of a given account for the specified cycle
'
customConfig:
description: Custom proration config, this will be considered if mode is CUSTOM
type: object
required:
- cycleStartDate
- cycleEndDate
- currentDate
properties:
cycleStartDate:
type: string
format: date-time
cycleEndDate:
type: string
format: date-time
currentDate:
type: string
format: date-time
lookupCycleConfig:
description: Cycle of proration to be looked up, this will be considered if mode is LOOKUP_CYCLE
type: object
required:
- accountId
properties:
currentDateTime:
description: Defaults to current date time if not provided
type: string
format: date-time
cycleEffectiveOn:
description: Defaults to current date time if not provided
type: string
format: date-time
accountId:
type: string
minLength: 1
entitlementOverageConfig:
title: EntitlementOverageConfig
description: Configuration for getting the entitlement overages
type: object
required:
- mode
properties:
mode:
type: string
enum:
- CUSTOM
- LOOKUP_CYCLE
description: 'Mode to get the entitlement overages for the entitlement overage rate cards
- CUSTOM: Use the entitlement overages provided in the request
- LOOKUP_CYCLE: Use the entitlement overages of a given account for the specified cycle
'
custom:
description: Quantity of entitlement overages, this will be considered if mode is CUSTOM
type: array
items:
type: object
title: EntitlementOverageEntry
required:
- featureId
- quantity
properties:
featureId:
type: string
minLength: 1
quantity:
type: number
lookupCycle:
description: Billing cycle of entitlement overages to be looked up, this will be considered if mode is LOOKUP_CYCLE
type: object
required:
- accountId
- billingCycleEndDate
properties:
billingCycleEndDate:
description: Effective date of the cycle, will be used to get the license entries of the cycle
type: string
format: date-time
accountId:
type: string
minLength: 1
GrantDetails:
description: Grant details of Credit Grant Rate Card
type: object
additionalProperties: false
required:
- priority
- expiryType
properties:
priority:
type: integer
minimum: 0
expiryType:
$ref: '#/components/schemas/ExpiryType'
expiryDuration:
type: string
format: duration
applicableEntityIds:
type: array
items:
type: string
LicenseRateCard:
title: LicenseRateCard
type: object
required:
- id
- rateValues
- ratePlan
- enableProration
properties:
id:
description: Unique Identifier of the attached AddOn
type: string
maxLength: 50
type:
$ref: '#/components/schemas/AddOnType'
displayName:
type: string
description: Name of the attached AddOn
tag:
type: string
description: A tag string to group licenseRateCards
invoiceTiming:
$ref: '#/components/schemas/InvoiceTiming'
usageCycle:
$ref: '#/components/schemas/UsageCycleInterval'
enableProration:
type: boolean
example: false
config:
$ref: '#/components/schemas/LicenseRateCardConfig'
ratePlan:
$ref: '#/components/schemas/RatePlan'
rateValues:
type: array
items:
$ref: '#/components/schemas/RateValue'
proratedRefundMode:
$ref: '#/components/schemas/ProratedRefundMode'
PricingCycleConfig:
type: object
description: Represents configurations related to pricing cycle
required:
- interval
- gracePeriod
properties:
interval:
$ref: '#/components/schemas/PricingCycleInterval'
startOffset:
type: object
description: "Represents the start of pricing cycle in terms of\n - dayOffset - number of days from beginning of week / month and\n - monthOffset - number of months from beginning of interval (quarter, half-year or year)\nNote: If a day with offset doesn't exist for a month, closest previous day is considered\nExamples:\nWEEKLY -\n - {dayOffset: 1, monthOffset: NIL} - First day of every week (Monday)\n - {dayOffset: 3, monthOffset: NIL} - 3rd day of every week (Wednesday)\n - {dayOffset: LAST, monthOffset: NIL} - Last day of every week (Sunday)\nMONTHLY -\n - {dayOffset: 1, monthOffset: NIL} - First day of every month\n - {dayOffset: 12, monthOffset: NIL} - 12th of every month\n - {dayOffset: 28, monthOffset: NIL} - 28th of every month. i.e, 28th of Jan, 28th of Feb, ...\n - {dayOffset: 30, monthOffset: NIL} - 30th of every month. i.e, 28th of Jan, 28th of Feb, ...\n - {dayOffset: LAST, monthOffset: NIL} - Last day of every month. i.e, 31st of Jan, 28th of Feb, ...\nQUARTERLY\n - {dayOffset: 15, monthOffset: FIRST} - 15th Jan, 15th Apr, 15th Jul and 15th Oct\n - {dayOffset: 15, monthOffset: 2} - 15th Feb, 15th May, 15th Aug and 15th Nov\n - {dayOffset: 15, monthOffset: LAST} - 15th Mar, 15th Jun, 15th Sep and 15th Dec\n - {dayOffset: LAST, monthOffset: FIRST} - 31st Jan, 30th Apr, 30th Jul and 31th Oct\nHALF_YEARLY\n - {dayOffset: 15, monthOffset: FIRST} - 15th Jan and 15th Jul\n - {dayOffset: 15, monthOffset: 4} - 15th Apr and 15th Oct\n - {dayOffset: 15, monthOffset: LAST} - 15th Jun and 15th Dec\nANNUALLY\n - {dayOffset: 15, monthOffset: FIRST} - 15th Jan\n - {dayOffset: 15, monthOffset: 1} - 15th Jan\n - {dayOffset: LAST, monthOffset: 2} - 29th Feb on Leap year, 28th otherwise \n - {dayOffset: 15, monthOffset: 8} - 15th Aug\n - {dayOffset: 15, monthOffset: LAST} - 15th Dec\n"
required:
- dayOffset
- monthOffset
properties:
dayOffset:
type: string
description: 'If interval is WEEKLY, min: "1" and max: "7" as strings. Spl. string allowed: LAST
Otherwise, min: "1" and max: "31" as strings. Spl. string allowed: LAST
'
monthOffset:
type: string
description: 'min: "1" and max: "12". Spl. string allowed: FIRST / LAST.
For QUARTERLY only 1 - 3 is allowed and for HALF_YEARLY 1 - 6. This being an optional field, shouldn''t be passed for MONTHLY.
'
gracePeriod:
type: integer
description: "Togai allows you to ingest past dated events that will be processed by a pricing cycle till the end grace period. \nFor example: Pricing cycle is Monthly from 1st to 30th and gracePeriod is 5 days which next month 1 to 5th date, you can ingest past dated events during this grace period.\n"
format: int32
example: 3
anniversaryCycle:
type: boolean
description: "Togai calculates the startOffsets based on the date of association instead of requiring from the user and \nthese offsets will be applied as an override if this flag is enabled.\nExamples:\nWEEKLY -\n - 23/10/2023 (Monday) - {dayOffset: 1, monthOffset: NIL} \n - 25/10/2023 (Wednesday) - {dayOffset: 3, monthOffset: NIL} \n - 29/10/2023 (Sunday) - {dayOffset: 7, monthOffset: NIL}\nMONTHLY -\n - 1st Oct - {dayOffset: 1, monthOffset: NIL}\n - 12th Oct - {dayOffset: 12, monthOffset: NIL}\n - 28th Oct - {dayOffset: 28, monthOffset: NIL}\n - 30th Oct - {dayOffset: 30, monthOffset: NIL}\n - 31th Oct - {dayOffset: LAST, monthOffset: NIL}\nQUARTERLY\n - 15th Jan, 15th Apr, 15th Jul and 15th Oct - {dayOffset: 15, monthOffset: 1}\n - 15th Feb, 15th May, 15th Aug and 15th Nov - {dayOffset: 15, monthOffset: 2} \n - 15th Mar, 15th Jun, 15th Sep and 15th Dec - {dayOffset: 15, monthOffset: 3}\nHALF_YEARLY\n - 15th Jan and 15th Jul - {dayOffset: 15, monthOffset: 1} \n - 15th Apr and 15th Oct - {dayOffset: 15, monthOffset: 4} \n - 15th Jun and 15th Dec - {dayOffset: 15, monthOffset: 6}\nANNUALLY\n - 15th Jan - {dayOffset: 15, monthOffset: 1}\n - 29th Feb on Leap year - {dayOffset: LAST, monthOffset: 2}\n - 28th Feb - {dayOffset: LAST, monthOffset: 2}\n - 15th Aug - {dayOffset: 15, monthOffset: 8}\n - 15th Dec - {dayOffset: 15, monthOffset: 12}\n"
CurrencySlabRateDetail:
type: object
description: The association of a currency along with its slab detail
additionalProperties: false
required:
- currency
- creditAmount
- slabDetails
properties:
currency:
type: string
creditAmount:
type: number
description: The amount of credit that needs to be credited
minimum: 0
slabDetails:
type: array
items:
$ref: '#/components/schemas/SlabDetail'
rateConfig:
type: object
additionalProperties:
type: string
RateValue:
type: object
description: Represents a rate
required:
- currency
- slabRates
properties:
currency:
type: string
slabRates:
type: array
minItems: 1
items:
$ref: '#/components/schemas/SlabRate'
rateConfig:
type: object
additionalProperties:
type: string
PricingModel:
type: string
description: "Togai supports two type of pricing model Tiered and Volume. Tiered pricing model applies respective slab and its rate to the usage value while volume pricing model applies the latest matching slab of the usage value and applies respective rate. \nFor more understanding read [Rate Cards](https://docs.togai.com/docs/priceplan#setting-up-multiple-rate-cards)\n"
enum:
- TIERED
- VOLUME
FeatureConfig:
description: Feature configuration object
type: object
additionalProperties: false
required:
- effectiveUntil
- featureCreditLimit
properties:
effectiveFrom:
type: string
format: duration
effectiveUntil:
type: string
format: duration
featureCreditLimit:
type: number
minimum: 0
PriceType:
type: string
enum:
- FLAT
- PER_UNIT
- PACKAGE
CurrencyRateValue:
type: object
required:
- currency
- rate
properties:
currency:
type: string
rate:
type: number
PricingCycleInterval:
type: string
description: Interval field allow you to define the billing interval you would like to set
enum:
- WEEKLY
- MONTHLY
- QUARTERLY
- HALF_YEARLY
- ANNUALLY
BillingConfig:
type: object
properties:
interval:
description: Represents the number of pricing cycle
# --- truncated at 32 KB (47 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/togai/refs/heads/main/openapi/togai-price-experimentation-api-openapi.yml