Plans API

Plans describe the relationship between your products and services and how customer accounts are billed for what they purchase. Plans contain information related to billing schedules, subscription and usage rate information, and are used by both contract and self-service customers.

The Plans API lets you setup and retrieve plans that belond to your organization.

Plans Endpoints

Each endpoint assumes a default base url: https://vault.revops.io/v1/

Plans List Resource

https://vault.revops.io/v1/plans

Supported Methods:

  • GET - Retrieves a list of plans
  • POST - Creates a plan

API Key Accessibility

All methods are only accessible on use of the secret key.

HTTP Method Public Key Secret Key
GET N/A
POST N/A

CREATE PLANS

POST /v1/plans

Summary:

Creates a new plan.

Description:

A new plan is created by sending a POST request to the resource URL /v1/plans. A plan is never associated with an account unless you explicitly associate it using accounts API.

There are four required parameters:

  1. friendly_name
  2. public
  3. cpq
  4. status

The remaining fields can defined as much of the object as you'd like.

HTTP Response Codes

Code Description Schema
201 Plan Plan
400 Invalid request. API Error

Example

This example creates an plan via the secret key.

$> curl  https://vault.revops.io/v1/plans \
        -X POST \
        -H 'Authorization: Bearer <secret_key>' \
        -H 'Content-type: application/json' \
        -d '{ "friendly_name": "superkalifragilisticexpealidocious",
        "public": "False",
        "cpq": "False",
        "status": "active" }'

Here is the same example in python.

from uuid import uuid4
import urllib.request
import json

api_key = "sk_sandbox_<yourkey>"
api_url = "https://vault.revops.io/v1/plans"

plan = {
    "friendly_name": "superkalifragilisticexpealidocious",
    "public": "False",
    "cpq": "False",
    "status": "active",
}

data = json.dumps(plan).encode('utf8')

request = urllib.request.Request(
  api_url,
  method='POST',
  data=data,
  headers={
    'Content-type': 'application/json',
    'Authorization': "Bearer {}".format(api_key),
  },
)
try:
    with urllib.request.urlopen(request) as response:
        json_response = response.read().decode('utf-8')
        print(json.loads(json_response))
except urllib.error.HTTPError as httperror:
    print(httperror.read().decode('utf-8'))

GET PLANS

GET /v1/plans

Summary:

Returns a list of Plans.

Query Parameters for filtering plans

In addition to pagination parameters , you can filter Plans by any of these parameters.

Name Description
status Filters Plans by status. Options are draft, live, archived.
public
cpq
startDate
endDate

Description:

A new plan is created by sending a POST request to the resource URL /v1/plans.

HTTP Response Codes

Code Description Schema
201 Created plan Plan
400 Invalid request API Error

Plans Instance Resource

https://vault.revops.io/v1/plans/:plan_id

Supported Methods:

  • GET - Retrieves Plan
  • POST - Updates existing Plan
URL Parameters
Name Description Required Schema
plan_id Unique identifier for the Plan generated by the API. Yes string

API Key Accessibility

HTTP Method Public Key Secret Key
GET N/A
POST N/A

UPDATE PLANS

POST /v1/plans/:plan_id

Example

$> curl  https://vault.revops.io/v1/plans/:plan_id \
        -H 'Authorization: Bearer <api_key>' \
        -H 'Content-type: application/json' \
        -d '{ "friendly_name": "superkalifragilisticexpealidocious",
        "public": "False",
        "cpq": "False",
        "status": "active" }'

Examples Response:

{
  "id": "plan_id",
  "uri": "/v1/plans/plan_id",
  "billing_provider_subscription_id": "",
  "cpq": false,
  "date_created": "2020-03-12T00:16:05+00:00",
  "date_updated": "2020-03-12T00:16:34.101505+00:00",
  "friendly_name": "New Plan ",
  "interval": "month",
  "interval_count": 1,
  "plan_group": {
    "id": "tag_a3c157310abc4a7bb05583bb4d2a8aa2",
    "date_created": null,
    "date_updated": null,
    "description": "",
    "icon": "",
    "name": "",
    "status": "active",
    "type": ""
  },
  "public": true,
  "skus": [],
  "status": "draft",
  "tags": [],
  "terms": {}
}

Description:

An existing plan is updated by sending a POST request to the resource URL.

Responses

Code Description Schema
200 Updated Plan Plan
400 Invalid request. API Error

Models

Plan

Plan describes the relationship between your business, the Account, and how their usage is billed. The list of properties for plan are:

Name Type Description Required
id string RevOps assigned unique identifier No
uri string RevOps assigned URI for accessing the Plan through a GET request No
date_created ISO8601 Datetime in UTC Time that the event was submitted to RevOps. Automatically created if not provided No
date_created ISO8601 Datetime in UTC Time that the last update event was submitted to RevOps. No
friendly_name string Friendly name provided to identify the plan Yes
status string Indicates the status of the Plan. Possible values are: live, draft, archived. Yes
public boolean Indicated if it is publicly available plan or custom one. true, false Yes
cpq boolean true, false Yes
is_default boolean Whether to make current plan default for all new accounts created. Possible values: true, false No
sku array of skus Refer to SKU model below No
terms array of terms Refer to Term model below No
tags array of tags Tags on the plan, refer to tag model below No
plan_group Tag Group to which this plan belongs to No

SKU

Name Type Description
adjusted_annual_price string (Money) The calculated adjusted annual price (12 x adjusted_price x quantity) of the SKU.
adjusted_monthly_price string (Money) The calculated adjusted monthly price (adjusted_price x quantity) of the SKU.
adjusted_net_price string (Money) The calculated adjusted total price of the SKU.
adjusted_price string (Money) The adjusted price of the SKU.
annual_price string (Money) The original annual price (12 x list_price x quantity) of the SKU.
billing_provider_plan_id string (UUID) A unique identifier for the SKU with your organization's billing provider.
billing_provider_product_id string (UUID) A unique identifier for the SKU with your organization's billing provider.
billing_provider_year_plan_id string (UUID) A unique identifier for the SKU with your organization's billing provider.
billing_provider_month_plan_id string (UUID) A unique identifier for the SKU with your organization's billing provider.
color string The color of the SKU's label.
contract_length int Number of months the Plan is active.
creator_id string (UUID) The unique identifier of the user who created the SKU.
crm_id string (UUID)
crm_pricebook2_id string (UUID)
crm_product2_id string (UUID)
currency string (ENUM) The currency of SKU. See Currency for possible values.
default_quantity int An integer value representing the default quantity of the SKU.
feature_flags array of FeatureFlag A list of feature flag objects configured for the SKU. See Feature Flag.
fraction_digits int Number of decimal places to display.
icon string (ENUM) The icon used to display the SKU.
id string (UUID) id is a globally unique identifier addressing the SKU.
is_discount boolean Is true when the SKU as a discount.
ledger_code string
line_item_description string Public description of the SKU that is displayed on customer facing contracts.
line_item_title string Public title of the SKU used on customer facing contracts.
list_price string (Money) The original price of the SKU based on administrator-defined values.
monthly_price string (Money) The original monthly price of the SKU based on administrator-defined values.
name string The internal name given to the SKU.
net_price string (Money) The total price of the SKU based on the original list_price.
order int Integer value that determines the order of the SKU on the Plan.
organization_id string (UUID) A unique identifier for the current organization.
product_code string The ledger code for what product the SKU's revenue is recognized in.
quantity int Integer value representing the total quantity of the SKU.
rates array of Rates Array of Rates the define the pricing of a metered SKU.
show_public_discount boolean Is true when the discount is visible to the customer.
sku_group string (ENUM) A Sku Group defines how to group the sku together on a quote. One of: professional-services, fixed-costs, variable-costs.
status string (ENUM) Status defines whether the SKU is active, retired, or archived.
tiering_model string A string representation of pre-paid usage rates.
tiering_model_type string (ENUM) Indicates if the metered billing is progressive, or non-progressive. One of: progressive, non-progressive
tiering_type string (ENUM) String values that indicates whether the SKU is for pre-paid or metered billing. Enumerated values: metered, prepaid
unit_name string A singular or plural noun describing the SKU in units.
unit_pricing_schedule string (ENUM) The schedule the SKU will be charged on. One of: monthly, annual, one-time, usage
updated_line_item_description string An updated public description of the SKU that is displayed on customer facing contracts.
Feature Flags
Name Type Description
id string (UUID) id is a globally unique identifier addressing the flag.
friendly_name string friendlyName is a label used to identify the feature flag.
mode string (ENUM) The type of feature flag. One of: gate, limit or number.
enabled boolean Is true when the feature flag is enabled.
value string Maximum value of limit feature flags and value of number feature flags.
Rate
Name Type Description
id string (UUID) id is a globally unique identifier addressing the rate.
name string The name given to the rate.
is_default boolean Is true when this this rate is the default rate.
metrics array of EventMetric An array of EventMetrics used in the rate.
negative_metrics array of EventMetric An array of EventMetrics used in the rate.
rate_table array of RatesTableRow An array of RatesTableRows that are used it define the price of a metered SKU.
EventMetric
Name Type Description
product string Product name associated with the metric
metric_name string Internal metric name
metric_value int Numeric value of the metric
metric_resolution string Time period associated with the metric
account_id string AccountId associated with the metric. This is the default account used for tracking usage metrics
sub_account_id string Subaccount associated with the metric
RatesTableRow Object

RatesTableRow capture the tiers used to compute volume and progressive based pricing:

Name Description
id id is a globally unique identifier addressing the flag.
monthly_rate Fixed monthly cost to include in the aggregate amount.
quantity Quantity used to calculate the amount for this rate tier. For volume based pricing, this value can be up to quantitymax. For progressive based pricing, this value will be up to (quantitymax - quantity_min).
quantity_max Maximum quantity for this tier, for last tier it is Infinity.
quantity_min Minimum quantity for this tier to kick in.

Term

Terms attach to the Plan when the Plan is created from a customer facing contract.

Name Type Description
copyBehavior string (ENUM) Determines how the Term is copied on new quotes. One of: deep-copy, reset-copy, or ignore-default-copy.
creatorId string (UUID) The unique identifier of the user who created the Term.
crmObject string
crmObjectField string
dateCreated ISO8601 Datetime ISO8601 Datetime in UTC of when the Term was created.
dateUpdated ISO8601 Datetime ISO8601 Datetime in UTC of the last modification to Term.
defaultValue string The default value assigned to the Term based on administrator-defined values.
description string Public description of the Term that is displayed on customer facing contracts.
hideLabel boolean Is true when the label is hidden on quotes, proposals, and deals.
icon string The icon name of the icon to display for the Term on quotes, proposals, and deals.
id string (UUID) id is a globally unique identifier addressing the sku.
internal boolean Is true when the Term is created by RevOps.
internalId string (UUID) he unique identifier for Terms created by RevOps.
isRequired boolean Is true when the Term is required on new quotes.
isStandard boolean Is true when the term is standard for the customer organization.
label string The label text to display for the Term.
labelContent string
name string The name assigned to the Term.
options array of options Options that are used for the dropdown term type.
order int Integer value for determining the order of the Term on customer facing contracts.
organization_id string (UUID) A unique identifier for the current organization.
placeholder string Text to display when the the input is empty.
properties dict Additional properties defined for the term.
renewalBehavior string (ENUM) Determines how the Term is copied on renewals. One of: deep-copy, reset-copy, or ignore-default-copy.
showInProposalBody boolean Is true when the Term is is displayed in the body of customer facing contracts.
showInProposalHeader boolean Is true when the Term is is displayed in the header of customer facing contracts.
termCategory string (ENUM) Determines which category to the Term belongs to. One of: legal
type string (ENUM) Identifies the type of legal term. See <term>.type for all possible values.
value string Value of the the accepted term. Possible values are determined by <term>.type

API Error Response Format

The standard API response format is used to indicate when we were not able to process the request.

Name Type Description Required
code integer RevOps Error Code No
type string RevOps Error Code No
message string Human readable description of the error code No